Tutorial

Monitoring

What the product holds, and how a log, a span and an error fit together

Checked 2026-09-28

Monitoring holds what a project says about itself: the log entries it emits, the traces its work belongs to, the errors it raises, the source maps that turn a minified stack back into your own code, and the one policy that decides what is removed before any of it is stored.

Everything is addressed under a project environment. The environment is not decoration: it is what a key is scoped to, what a query is bounded by, and what the scrubbing policy belongs to.

#Log entries

A Log Entry is one typed, bounded log record of a project environment, correlated to a trace. log_time, severity and body are required, and severity is one of trace, debug, info, warn, error and fatal. service_name says which service emitted it, attributes carries typed values, and trace_id with span_id places the record on a trace.

Entries are immutable, and ingest is idempotent per batch: the same Idempotency-Key and digest replays the same batch, while a different digest under the same key conflicts. A retry is therefore safe to send, and a changed body under the same key is refused rather than written twice.

#Traces

A Trace is every span sharing one W3C trace id in a project environment, and the id is t followed by the 32-hex trace id. A span carries its trace_id, span_id, span_name, service_name, start_time and end_time; kind is one of internal, server, client, producer and consumer, and parent_span_id is empty on a root span.

The trace itself is derived from its spans: the root span's name and service, the earliest start, the latest end, and whether any span has an error status. A query answers with those summaries and no spans; reading one trace answers with every span in start order.

#Errors

An Error Group is the deterministic grouping of error occurrences by fingerprint, and an Error Event is one immutable error occurrence, with breadcrumbs and correlation.

Release is an attribute of each occurrence and never part of the group key, so one bug stays one group across releases. A group's state — unresolved, acknowledged or resolved — is the whole of its triage. Errors covers grouping, capture and the three triage calls.

#Source maps

A Source Map is one uploaded JavaScript source map of one release of a project environment. Captured stack frames of that release whose file matches file_url are mapped back to the original source before grouping, which is what makes a group a bug in your code rather than a minified build. Source maps covers the upload and what it changes.

#Scrubbing

Every environment has one Scrubbing Policy: what is removed from every captured error before it is stored. The default rules always apply — a field named like a password, a token or a card is replaced, and so is anything that looks like a card number, a bearer token, a JWT or a Sylphx secret key. The environment's policy adds to the defaults; it cannot remove them. Scrubbing states the rules in full.

#Names

A resource's name is its path, and the same path works in the API, the CLI and the console.

Log entry

orgs/{org}/projects/{project}/envs/{env}/log_entries/{log_entry}

Trace

orgs/{org}/projects/{project}/envs/{env}/traces/{trace}

Error group

orgs/{org}/projects/{project}/envs/{env}/error_groups/{error_group}

Error event

orgs/{org}/projects/{project}/envs/{env}/error_groups/{error_group}/error_events/{error_event}

Source map

orgs/{org}/projects/{project}/envs/{env}/source_maps/{source_map}

Scrubbing policy

orgs/{org}/projects/{project}/envs/{env}/scrubbing_policies/default

#Scopes

observability:read covers every read. observability:ingest covers what comes in from a running system: batches of log entries, batches of spans, and captured errors. observability:write covers what changes after ingest — acknowledging, resolving or reopening a group, uploading a source map, and writing the scrubbing policy.

A browser captures errors with a publishable key that holds observability:ingest: the call allows CORS and is rate-limited per environment. Keys and scopes has what a publishable key may hold and what it may not.