Status

OPA can periodically report status updates to remote HTTP servers. The updates contain status information for OPA itself as well as the Bundles that have been downloaded and activated.

OPA sends status reports whenever one of the following happens:

  • Bundles are downloaded and activated – If the bundle download or activation fails for any reason, the status update will include error information describing the failure. This includes Discovery bundles.
  • A plugin state has changed – All plugin status is reported, and an update to any plugin will trigger a Status API report which contains the latest state.

The status updates will include a set of labels that uniquely identify the OPA instance. OPA automatically includes an id value in the label set that provides a globally unique identifier or the running OPA instance and a version value that provides the version of OPA.

See the Configuration Reference for configuration details.

Status Service API

OPA expects the service to expose an API endpoint that will receive status updates.

  1. POST /status[/<partition_name>] HTTP/1.1
  2. Content-Type: application/json

The partition name is an optional path segment that can be used to route status updates to different backends. If the partition name is not configured on the agent, updates will be sent to /status.

  1. {
  2.   "labels": {
  3.     "app": "my-example-app",
  4.     "id": "1780d507-aea2-45cc-ae50-fa153c8e4a5a",
  5.     "version": "v0.28.0"
  6.   },
  7.   "bundles": {
  8.     "http/example/authz": {
  9.       "active_revision": "ABC",
  10.       "last_request": "2018-01-01T00:00:00.000Z",
  11.       "last_successful_request": "2018-01-01T00:00:00.000Z",
  12.       "last_successful_download": "2018-01-01T00:00:00.000Z",
  13.       "last_successful_activation": "2018-01-01T00:00:00.000Z",
  14.       "metrics": {
  15.         "timer_rego_data_parse_ns": 12345,
  16.         "timer_rego_module_compile_ns": 12345,
  17.         "timer_rego_module_parse_ns": 12345
  18.       }
  19.     }
  20.   },
  21.   "plugins": {
  22.     "bundle": {
  23.       "state": "OK"
  24.     },
  25.     "discovery": {
  26.       "state": "OK"
  27.     },
  28.     "status": {
  29.       "state": "OK"
  30.     }
  31.   },
  32.   "metrics": {
  33.     "prometheus": {
  34.       "go_gc_duration_seconds": {
  35.         "help": "A summary of the GC invocation durations.",
  36.         "metric": [
  37.           {
  38.             "summary": {
  39.               "quantile": [
  40.                 {
  41.                   "quantile": 0,
  42.                   "value": 0.000011799
  43.                 },
  44.                 {
  45.                   "quantile": 0.25,
  46.                   "value": 0.000011905
  47.                 },
  48.                 {
  49.                   "quantile": 0.5,
  50.                   "value": 0.000040002
  51.                 },
  52.                 {
  53.                   "quantile": 0.75,
  54.                   "value": 0.000065238
  55.                 },
  56.                 {
  57.                   "quantile": 1,
  58.                   "value": 0.000104897
  59.                 }
  60.               ],
  61.               "sample_count": 7,
  62.               "sample_sum": 0.000309117
  63.             }
  64.           }
  65.         ],
  66.         "name": "go_gc_duration_seconds",
  67.         "type": 2
  68.       },
  69. ------------------------------8< SNIP 8<------------------------------
  70.       "http_request_duration_seconds": {
  71.         "help": "A histogram of duration for requests.",
  72.         "metric": [
  73.           {
  74.             "histogram": {
  75.               "bucket": [
  76.                 {
  77.                   "cumulative_count": 1,
  78.                   "upper_bound": 0.005
  79.                 },
  80.                 {
  81.                   "cumulative_count": 1,
  82.                   "upper_bound": 0.01
  83.                 },
  84.                 {
  85.                   "cumulative_count": 1,
  86.                   "upper_bound": 0.025
  87.                 },
  88.                 {
  89.                   "cumulative_count": 1,
  90.                   "upper_bound": 0.05
  91.                 },
  92.                 {
  93.                   "cumulative_count": 1,
  94.                   "upper_bound": 0.1
  95.                 },
  96.                 {
  97.                   "cumulative_count": 1,
  98.                   "upper_bound": 0.25
  99.                 },
  100.                 {
  101.                   "cumulative_count": 1,
  102.                   "upper_bound": 0.5
  103.                 },
  104.                 {
  105.                   "cumulative_count": 1,
  106.                   "upper_bound": 1
  107.                 },
  108.                 {
  109.                   "cumulative_count": 1,
  110.                   "upper_bound": 2.5
  111.                 },
  112.                 {
  113.                   "cumulative_count": 1,
  114.                   "upper_bound": 5
  115.                 },
  116.                 {
  117.                   "cumulative_count": 1,
  118.                   "upper_bound": 10
  119.                 }
  120.               ],
  121.               "sample_count": 1,
  122.               "sample_sum": 0.003157399
  123.             },
  124.             "label": [
  125.               {
  126.                 "name": "code",
  127.                 "value": "200"
  128.               },
  129.               {
  130.                 "name": "handler",
  131.                 "value": "v1/data"
  132.               },
  133.               {
  134.                 "name": "method",
  135.                 "value": "get"
  136.               }
  137.             ]
  138.           }
  139.         ],
  140.         "name": "http_request_duration_seconds",
  141.         "type": 4
  142.       }
  143.     }
  144.   }
  145. }

Status updates contain the following fields:

FieldTypeDescription
labelsobjectSet of key-value pairs that uniquely identify the OPA instance.
bundle.namestring(Deprecated) Name of bundle that the OPA instance is configured to download. Omitted when bundles are configured.
bundle.activerevisionstring(Deprecated) Opaque revision identifier of the last successful activation. Omitted when bundles are configured.
bundle.last_successful_downloadstring(Deprecated) RFC3339 timestamp of last successful bundle download. Omitted when bundles are configured.
bundle.last_successful_activationstring(Deprecated) RFC3339 timestamp of last successful bundle activation. Omitted when bundles are configured.
bundlesobjectSet of objects describing the status for each bundle configured with OPA.
bundles[].namestringName of bundle that the OPA instance is configured to download.
bundles[].active_revisionstringOpaque revision identifier of the last successful activation.
bundles[].lastrequeststringRFC3339 timestamp of last bundle request. This timestamp should be >= to the successful request timestamp in normal operation.
bundles[].lastsuccessful_requeststringRFC3339 timestamp of last successful bundle request. This timestamp should be >= to the successful download timestamp in normal operation.
bundles[].lastsuccessful_downloadstringRFC3339 timestamp of last successful bundle download.
bundles[].lastsuccessful_activationstringRFC3339 timestamp of last successful bundle activation.
bundles[].metricsobjectMetrics from the last update of the bundle.
discovery.namestringName of discovery bundle that the OPA instance is configured to download.
discovery.activerevisionstringOpaque revision identifier of the last successful discovery activation.
discovery.last_requeststringRFC3339 timestamp of last discovery bundle request. This timestamp should be >= to the successful request timestamp in normal operation.
discovery.last_successful_requeststringRFC3339 timestamp of last successful discovery bundle request. This timestamp should be >= to the successful download timestamp in normal operation.
discovery.last_successful_downloadstringRFC3339 timestamp of last successful discovery bundle download.
discovery.last_successful_activationstringRFC3339 timestamp of last successful discovery bundle activation.
pluginsobjectA set of objects describing the state of configured plugins in OPA’s runtime.
plugins[].statestringThe state of each plugin.
metrics.prometheusobjectGlobal performance metrics for the OPA instance.

If the bundle download or activation failed, the status update will contain the following additional fields.

FieldTypeDescription
bundle.codestringIf present, indicates error(s) occurred.
bundle.messagestringHuman readable messages describing the error(s).
bundle.errorsarrayCollection of detailed parse or compile errors that occurred during activation.

If the discovery bundle download or activation failed, the status update will contain the following additional fields.

FieldTypeDescription
discovery.codestringIf present, indicates error(s) occurred.
discovery.messagestringHuman readable messages describing the error(s).
discovery.errorsarrayCollection of detailed parse or compile errors that occurred during activation.

Services should reply with HTTP status 200 OK if the status update is processed successfully.

Local Status Logs

Local console logging of status updates can be enabled via the console config option. This does not require any remote server. Example of minimal config to enable:

  1. status:
  2.     console: true

This will dump all status updates to the console. See Configuration Reference for more details.

Warning: Status update messages are somewhat infrequent but can be very verbose! The metrics.prometheus portion of the status update in particular can create a considerable amount of log text at info level.