Skip to content
StratumStratum Docs

List every Stratum-emitted metric with its kind, unit, description, declared labels, category, and prometheus wire name..

GET
/v1/projects/{projectId}/observability/metric-catalog
Code sample: Shell / cURL
curl --request GET \
  --url 'https://stratum.example.com/v1/projects/example/observability/metric-catalog?category=platform&kind=counter' \
  --header 'Authorization: Bearer <token>'

The catalog is built from the obs SDK’s instrument registry every NewCounter / NewGauge / NewHistogram call auto-registers an entry, so the catalog cannot drift from what the running binary actually emits.

Use this to populate the in-product Observability reference page, validate dashboards-as-code before applying, and feed query-builder autocomplete. The wireName field is the canonical reference for vmalert rules + customer PromQL (:267); the name field is the dotted SDK name useful for grep-spelunking emission sites.

Project scoping is for IAM authorization; the catalog is process-global and identical across projects.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
projectId
required
string
/^p-[a-z0-9-]+$/

Query Parameters

Section titled “Query Parameters”
category
string
Allowed values: platform workload

Narrow to platform | workload metrics. Omit for both. .

kind
string
Allowed values: counter gauge histogram

Narrow to a single instrument primitive. Omit for all kinds..

Responses

Section titled “Responses”

200

Section titled “200”

Metric catalog.

Media typeapplication/json
object
items
required
Array<object>

One row of the SDK-introspected metric catalog. Generated from the obs SDK’s instrument registry — every NewCounter / NewGauge / NewHistogram call adds an entry; the catalog is the source of truth for what the running binary emits.

object
name
required

SDK declaration name with dots (e.g. “stratum.iam.logins_total”). Use this when reading stratum source code or grep-spelunking emission sites.

string
wireName
required

Prometheus / VictoriaMetrics wire name produced by the otel-collector prometheusremotewriteexporter (dots → underscores; histograms also get a long-form unit suffix). This is what vmalert rules and customer PromQL queries must reference.:267.

string
kind
required

instrument primitive.

string
Allowed values: counter gauge histogram
unit

UCUM unit (e.g. “1”, “ms”, “By”).

string
description

Human-readable description registered at the SDK.

string
category
required

subject taxonomy: platform = Stratum’s own innards; workload = customer-visible resources. Tagged as a label on every emission.

string
Allowed values: platform workload
labels

Low-cardinality attribute keys this metric expects callers to stamp via obs.Label{}. Tenant labels (organization_id, project_id) and the category label are auto-attached on every emission and NOT listed here. Optional — empty means labels have not been declared at registration.

Array<string>
buckets

Histogram bucket boundaries (ms by convention). Empty for counters and gauges.

Array<number>
stability
required

Stability marker for catalog consumers. Defaults to stable. Experimental signals the name/labels may change without deprecation; deprecated signals scheduled removal.

string
default: stable
Allowed values: stable experimental deprecated

Example 

{
  "items": [
    {
      "name": "stratum.iam.logins_total",
      "wireName": "stratum_iam_logins_total",
      "kind": "counter",
      "unit": "1",
      "category": "platform",
      "stability": "stable"
    }
  ]
}

400

Section titled “400”

Bad request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
>= 400 <= 599
detail
string
instance
string format: uri-reference
requestId
required
string
code
required
string
issues

The findings of a rejected IAM policy document (custom and resource policies).

Array<object>

One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.

object
code
required

The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.

string
statement
required

Index of the statement at fault; -1 for the document as a whole.

integer
>= -1
detail
required
string
action

The offending action, where one is at fault (ACTION_NOT_APPLICABLE).

string
errors

Field errors, for codes that carry them: each problem at its field (see FieldError). Documented on the responses that set it, e.g. approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED. Absent otherwise.

Array<object>

One field’s problem, the stage-2 installer API’s shape. field is the field’s path, message what is wrong with it.

object
field
required

The field’s path, e.g. links[0].interface, disks[1].confirm, mgmt.address or role; empty for the whole request.

string
message
required
string
details

Structured facts about the refusal, for codes that carry them. The shape is fixed per code and documented on the response that answers it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and IMAGE_IN_USE. Absent for codes that carry none.

object
key
additional properties
any

Example 

{
  "issues": [
    {
      "code": "ACTION_NOT_APPLICABLE",
      "action": "compute:CreateVpc"
    }
  ]
}