Observability API
Use canonical observability operations for new metrics integrations. This guide describes the current source contract; check the installed server version and its OpenAPI document before migrating a client. A newer source guide or cached schema does not add routes to an older installation.
Discover before querying
Section titled “Discover before querying”| Operation | Purpose |
|---|---|
GET /api/observability/environments?tenant=... |
Discover visible environments for an authorized tenant. |
POST /api/observability/catalog |
Discover signal capabilities and resource kinds. |
POST /api/observability/query |
Submit a typed, bounded query for the selected signal. |
POST /api/observability/resources |
Resolve scoped execution resources. |
GET /api/observability/worker-throughput?tenant=... |
Read the completed-minute per-Worker Output/Bytes display rate. |
For metrics stream discovery, query with view.kind=metrics and target.kind=catalog. Then use the discovered stream_id with target.kind=series to discover series. Select the appropriate point target: number_points, histogram_points, exponential_histogram_points or summary_points. The top-level catalog is not itself the list of metric streams.
Use the complete request shape documented by the installed ObservabilityQueryRequest contract, including the authorized environment, bounded time range and pagination. The returned coverage, warnings and continuation state are part of the result; an empty or incomplete frame is not automatically a measured zero. Counters, gauges, histogram temporality and reset semantics must remain distinct. Exact Job counters use decimal strings; do not round them through a floating-point conversion.
Authentication establishes tenant visibility. Request labels, resource attributes and caller-supplied identifiers do not grant authority. Use an identity permitted for the operation and handle 401/403 explicitly; do not substitute a broader credential merely to obtain data.
Migrate legacy metric clients
Section titled “Migrate legacy metric clients”| Old operation | Current integration path |
|---|---|
GET /api/metrics/current-rate |
GET /api/observability/worker-throughput |
GET /api/metrics/series |
Canonical catalog plus metrics stream/series discovery through the query operation |
GET /api/metrics/series/{series_id}/samples |
Typed metric point targets on POST /api/observability/query |
POST /api/metrics/query/bucketed |
Explicit canonical query and supported presentation |
The integer-series API retirement has no redirect or old-body forwarding adapter. Do not carry an old integer series ID into a canonical selector or expect the same response schema. Historical documents for older releases can still contain those routes; they are not the integration contract for a release containing the retirement.
Worker throughput is a display rate from completed-minute canonical output-byte coverage. It is not an ingest/rating or commercial-volume total. Missing evidence must remain unknown rather than being reported as zero.
Save a canonical query
Section titled “Save a canonical query”Use POST /api/observability/saved-queries?tenant=... to create a saved query, and PUT /api/observability/saved-queries/{id}?tenant=... to update one. Submit CanonicalSavedQueryInput.query as the plain typed ObservabilityQueryRequest, with an agreeing navigation href. Stored/read query responses use the canonical_v1 discriminator; it is not a wrapper to add to the create request.
Keep visibility, owner/tenant checks, expected revision and pin semantics from the installed contract. New legacy MetricsBucketed writes through /api/analytics/saved-investigations are refused. A historical saved record that remains readable as metadata must not be re-executed, translated or re-saved merely by changing its discriminator.
Readiness and removal
Section titled “Readiness and removal”A successful metrics query describes its returned scope, time and coverage. It does not certify every Worker or external destination. Likewise, successful Job removal acknowledges its supported execution/assignment lifecycle; metrics settlement and retained history publication remain independent. Do not delete, replay or directly inspect runtime databases to migrate an API client.
See Monitoring, Runtime Evidence and Receipts, and API stability and versioning.