OTel Facets

Register an OTel attribute key as a facet.

Changed on

Assigns the key to the lowest available slot column (1..=20) and inserts the mapping into Postgres with status: pending. Returns immediately — the historical backfill (populating the slot column for spans already ingested before this call) runs entirely in the background, advanced by a periodic poller; poll GET /otel/facets and check the returned status (pending -> running -> completed/failed) to track progress. New spans start getting the attribute written into the slot column right away, independent of backfill progress.

post/otel/facets

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/otel/facets
  • Auth: HTTP bearer

Request body

attribute_keystring required

The OTel attribute key to facet (e.g. enduser.id, galachain.contract). Must be non-empty, ≤200 characters, and not already registered.

Response

Facet registered

attribute_keystring required

The OTel attribute key, e.g. enduser.id or galachain.contract.

backend'clickhouse' | 'timescaledb' required

Which storage engine a facet was created against. A deployment only ever runs one backend at a time (see plugin.rs's storage selection), but stamping it on each row keeps the status fields unambiguous.

created_atstring required
error_messagestring nullable

Populated when status = failed, explaining why.

rows_backfilledinteger required

Rows backfilled so far. Only meaningful for the timescaledb backend — the clickhouse backend's mutation doesn't expose a row count until it's done, so this stays 0 there even while running.

slotinteger required

The slot column index 1..=20 (facet_attr_N).

status'pending' | 'running' | 'completed' | 'failed' | 'deleting' required

Backfill/delete-clear lifecycle for a facet. See the module docs for how the poller advances a facet through these states.

Example response

{
  "created_at": "2025-10-12T12:15:47.609192Z"
}

Changes

  • 4b228ebed583Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 1dc3e6788214Revision changes
    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status