Observer Docs

The agent is configured through environment variables. There is no configuration file; this keeps the runtime container immutable and the deployment surface small.

Required

Variable	Notes
`AGENT_KEY`	Authentication key issued by the cloud. Format `obs_live_<43 base64url chars>`. The cloud stores its hash, never the plaintext.

Cloud connection

Variable	Default	Notes
`CLOUD_SERVER_URL`	`https://use.observer`	Base URL of Observer Cloud. Agents before 1.6.0 default to `https://localhost:3000` and need it set explicitly.

Network

Proxy and trust-store settings. The agent’s runtime reads these directly, so they apply to the connection to Observer Cloud, Prometheus queries and HTTP-based probes alike. See Run behind a proxy or in a restricted network.

Variable	Default	Notes
`HTTPS_PROXY`	unset	Proxy URL for HTTPS requests, for example `http://proxy.corp.example:3128`. Credentials, if any, go in the URL.
`HTTP_PROXY`	unset	Proxy URL for plain HTTP requests.
`NO_PROXY`	unset	Comma-separated hosts and domain suffixes that bypass the proxy, for example `localhost,127.0.0.1,.corp.example`. No CIDR support. List internal probe targets and Prometheus here.
`NODE_EXTRA_CA_CERTS`	unset	Path to a PEM file with extra CA certificates to trust, in addition to the built-in store. Use it for a TLS-intercepting proxy or a private CA. Read at startup.
`NODE_TLS_REJECT_UNAUTHORIZED`	`1`	Setting `0` disables certificate verification for every HTTPS request the agent makes, including the cloud and all probes. Do not use in production; use `NODE_EXTRA_CA_CERTS` instead.

Required for Prometheus probes

Variable	Notes
`PROMETHEUS_SERVER_URL`	Base URL of the Prometheus (or Prometheus-compatible API) the agent should query. Used as the default for every Prometheus metric, overridable per-metric via `prometheus_url` in the metric’s source config. Keep any path prefix, for example `https://mimir.example.com/prometheus`; the agent appends `/api/v1/query` to it. Optional: when unset, the agent logs a warning at startup and Prometheus metrics without their own `prometheus_url` report `no_data`. Other probe types are unaffected.

Optional Prometheus auth

Variable	Default	Notes
`PROMETHEUS_BASIC_AUTH_ENABLED`	`true`	Set to any value other than `true` to disable. When enabled and both `PROMETHEUS_USERNAME` and `PROMETHEUS_PASSWORD` are set, the agent sends `Authorization: Basic <encoded>`.
`PROMETHEUS_USERNAME`	`admin`	Basic auth username.
`PROMETHEUS_PASSWORD`	empty	Basic auth password. Treat as a secret.
`PROMETHEUS_BEARER_TOKEN`	empty	Agent 1.6.2+. Sends `Authorization: Bearer <token>`. Cannot be combined with basic auth: if basic auth is also in effect, the agent logs an error at startup and Prometheus metrics report `no_data` with reason `prometheus_auth_conflict`. Treat as a secret.
`PROMETHEUS_TENANT_ID`	empty	Agent 1.6.2+. Sent as the `X-Scope-OrgID` header, the tenant header of Grafana Mimir and Cortex.
`PROMETHEUS_HEADERS`	empty	Agent 1.6.2+. Extra request headers for any other need, as a JSON object (`{"X-Api-Key": "..."}`) or a list (`X-Api-Key: ...; X-Other: ...`). It cannot repeat `Authorization` when basic auth or a bearer token is set, nor `X-Scope-OrgID` when `PROMETHEUS_TENANT_ID` is set. An invalid value makes Prometheus metrics report `no_data` with reason `prometheus_headers_invalid`. Header values are never logged. Treat as a secret.

These apply to every Prometheus metric the agent runs. See Grafana Mimir and other Prometheus-compatible backends for examples.

Dashboard

Variable	Default	Notes
`ENABLE_DEBUG_DASHBOARD`	`true`	Set to `false` to disable the local debug dashboard.
`DEBUG_DASHBOARD_HOST`	`127.0.0.1`	Bind address for the dashboard HTTP listener. A non-loopback value (for example `0.0.0.0`) is downgraded back to `127.0.0.1` unless `DEBUG_DASHBOARD_TOKEN` is set.
`DEBUG_DASHBOARD_TOKEN`	empty	Required to bind the dashboard to a non-loopback address. Without it, a non-loopback `DEBUG_DASHBOARD_HOST` falls back to `127.0.0.1`. The token is enforced only on a non-loopback bind: with the default loopback bind, the dashboard does not ask for it.
`DEBUG_DASHBOARD_PORT`	`10101`	Port for the dashboard HTTP listener.

Logging

Variable	Default	Notes
`BROADCAST_LOGS`	`false`	When `true`, the agent forwards its log lines at or above `LOG_BROADCAST_LEVEL` to the console’s live log viewer. PromQL query strings are always redacted to a SHA-256 prefix and length, regardless of this flag.
`LOG_BROADCAST_LEVEL`	`WARN`	Minimum level forwarded when `BROADCAST_LOGS=true`. One of `DEBUG`, `INFO`, `WARN`, `ERROR`.
`VERBOSE`	`false`	Local stdout verbosity.

Live logs in the console

With BROADCAST_LOGS=true, open the agent in the console and select the Logs tab, or use Logs on the agent’s row in the agents table. Both show the same live viewer.

Live only. Lines stream while the viewer is open. Nothing is stored: lines the agent sends while no viewer is open, or while the viewer is disconnected, are not kept. The viewer holds the newest 500 lines until you leave it.
Filters. Pick a minimum level (all levels, info and above, warn and above, error only) and search the lines. Copy copies the lines shown, or all lines when no filter is set.
Controls. The viewer follows the newest line; scroll up to stop following. Pause holds new lines until you select Resume. Clear empties the viewer.
States. The viewer shows Connecting, Connected, Live while lines arrive, Reconnecting with a retry countdown and a Retry now button when the stream drops, and Agent offline with the time of the last heartbeat when the agent is not reporting.

An empty viewer on a healthy agent is normal: by default only WARN and ERROR lines are forwarded. To see routine activity, set the level to INFO and restart the agent:

BROADCAST_LOGS=true
LOG_BROADCAST_LEVEL=INFO

From agent 1.7.2, every check result that resolves to no data is logged at WARN with its reason code and how long the check took, so it reaches the viewer at the default level:

no_data: http metric=<metric id> reason=connect_failed elapsed_ms=10003

The console stores only the latest reason for each check. These lines are the history, which helps diagnose a check that fails now and then.

Local queue

Variable	Default	Notes
`BUFFER_PATH`	`./observer-agent-buffer.db`	Path to the agent’s local SQLite write-ahead queue file. The heartbeat relay queue sits next to it (`-relay` suffix). In containers use `/data/observer-agent-buffer.db` with a volume on `/data` (the default in agent images 1.6.0 and later).
`BUFFER_MAX_ROWS`	`200000`	Hard cap on queued readings (`10000` before agent 1.7.3). When the queue reaches the cap, oldest entries are evicted to admit new ones. One reading is about 300 bytes, so the default uses up to about 60 MB and holds about 33 hours for 50 metrics every 30 seconds. See Local queue.

OpenTelemetry receiver

Read only when at least one metric with source type otlp is configured. Until then the receiver never starts and no port is opened. See Receive metrics over OpenTelemetry (OTLP).

Variable	Default	Notes
`OBSERVER_OTLP_LISTEN_ADDR`	`127.0.0.1:4318`	Bind address for the OTLP/HTTP receiver. Binding a non-loopback address requires `OBSERVER_OTLP_BEARER_TOKEN`. Without it the receiver does not start and OTLP metrics report `push_source_init_failed`.
`OBSERVER_OTLP_BEARER_TOKEN`	empty	Bearer token senders must present in the `Authorization` header. Compared in constant time.
`OBSERVER_OTLP_MAX_BUFFER_POINTS`	`1000`	Maximum distinct streams (metric name x attribute fingerprint) held in memory. Past the cap the oldest stream is evicted.
`OBSERVER_OTLP_DISABLE`	unset	Set to `true` to skip the receiver entirely, even when OTLP metrics are configured.
`OBSERVER_OTLP_MAX_BODY_BYTES`	`16777216` (16 MB)	Hard cap on a single OTLP request body, so an oversized payload cannot exhaust agent memory. Values below the 1 MB floor are ignored and the default applies.

Heartbeat relay

Requires agent 1.6.0 or later. The relay is off by default. See Heartbeat relay.

Variable	Default	Notes
`HEARTBEAT_RELAY_ENABLED`	`false`	Set `true` to start the heartbeat relay for jobs without internet access.
`HEARTBEAT_RELAY_HOST`	`127.0.0.1`	Relay bind address. Loopback only by default; set `0.0.0.0` to accept pings from other hosts or pods.
`HEARTBEAT_RELAY_PORT`	`10102`	Port the relay listens on.

Other

Variable	Default	Notes
`SKIP_SSL_VERIFICATION`	`false`	Disables TLS verification on cloud-bound requests. Development only. For a TLS-intercepting proxy, trust its CA with `NODE_EXTRA_CA_CERTS` instead.
`NODE_ENV`	unset	Set to `production` in the published image. The agent does not change behavior based on it.

Sensitive values in the dashboardEvery value the debug dashboard shows is masked, including the ones that are not secrets. A value shorter than 20 characters is replaced with **** outright; a longer one keeps a first-4 … last-2 hint, enough to tell two keys apart and never enough to recover one.DEBUG_DASHBOARD_TOKEN is listed with its value replaced by •hidden•, never even partially shown: it is the credential that protects the page.Variables outside the dashboard’s allowlist are omitted entirely. The allowlist is intentionally narrow; everything outside it does not appear regardless of name or value.

Quickstart

Concepts

Guides

Reference

Environment variables

Required

Cloud connection

Network

Required for Prometheus probes

Optional Prometheus auth

Dashboard

Logging

Live logs in the console

Local queue

OpenTelemetry receiver

Heartbeat relay

Other

​Required

​Cloud connection

​Network

​Required for Prometheus probes

​Optional Prometheus auth

​Dashboard

​Logging

​Live logs in the console

​Local queue

​OpenTelemetry receiver

​Heartbeat relay

​Other

Required

Cloud connection

Network

Required for Prometheus probes

Optional Prometheus auth

Dashboard

Logging

Live logs in the console

Local queue

OpenTelemetry receiver

Heartbeat relay

Other