Metadata

Free-form JSON you attach to traces and steps. obsrv indexes the keys you write and lets you filter by them in the dashboard and the API.

Setting metadata

t.set_metadata(user_id="u_a72c", release="v3.2.1")
t.set_metadata_path("billing.plan", "pro")
t.set_metadata_path("user.cohort", "early-access")

Filtering by metadata

The list-traces endpoint supports repeated meta_key andmeta_value query pairs. Use dot paths to filter on nested keys.

GET /v1/traces?meta_key=release&meta_value=v3.2.1&meta_key=user.cohort&meta_value=early-access

Field discovery

The dashboard discovers metadata keys from real traces and offers them in the filter bar. New keys appear without a code change. obsrv types each key based on the values it's seen so the filter UI offers the right operator (string, number, boolean, enum).

What to put in metadata

Recommended:

release — your build SHA or version.
user_id / session_id — for cross-trace correlation.
prompt_version — for tracking prompt changes.
environment — prod, staging, local.

Don't store secrets, raw PII, or unbounded blobs in metadata.

← Step

Metrics →