yatta/observe

Groups a pre-built occurrence into the issue queue.

Reads every recorded label set back, for .

Returns copies rather than the live state, so a caller cannot mutate the registry's buckets or samples through what it is handed.

Reads every recorded metric back.

The registry previously only accepted writes: a counter could be incremented but there was no supported way to read its value, so a metric could be recorded, exported nowhere, and never checked. Label sets are returned as strings rather than parsed, because the registry does not keep the original label object and reconstructing one would mean encoding keys back into an object with a different key order.

Traces developers have marked as known-good baselines.

Source lookup for trace-to-code.

Replaceable, and unset by default: a production build usually has no sources on disk, and reading files off a running server is not something to enable implicitly.

Retained metric samples, bounded — an unbounded series is itself a leak.

Single source of truth for the slow-query threshold.

v5 instrumented at 50ms but filtered the buffer at 100ms, so queries in the 50–100ms band were announced as slow yet never recorded. Both sides now read this value.

Correlate everything recorded about one issue fingerprint.

Returns `null` for an unknown fingerprint. A returned analysis may contain no suspects — that means the data did not explain the failure, which is a legitimate answer, reported as such rather than filled in with a guess.

Adaptive threshold for one metric, or null while the baseline is immature.

Returning null rather than a number is deliberate: a threshold derived from four samples would flag normal traffic as anomalous.

Evaluate current values against their own history.

Memory growth over the baseline window.

Self-contained incident payload, suitable for a model or a colleague with

Conclusions travel with the evidence and the reasons they might be wrong, so a reader cannot act on a suspicion without seeing how weak it is.

Describe an action without performing it.

Separate from `performAction` so a confirmation prompt can show exactly what will be affected before anything happens.

Perform a guarded action.

Enforces confirmation and an idempotency key for anything that changes state, and records an audit entry either way — including for attempts that were blocked, since "someone tried to purge the queue at 3am" is itself the record worth keeping.

Capture a live trace as a named baseline to compare future runs against.

Compare a live trace against a saved baseline, newest first.

Source lines around a stack frame.

Returns a snippet whose `missing` flag is set when no resolver is installed or the file is absent, rather than pretending the line is unknown.

Dependency graph inferred from recorded spans.

Repeated identical queries under one parent — the N+1 shape.

Evaluate one objective.

Evaluate every configured objective. Empty when none are configured.

Queue and job health, using retained history for backlog direction.

Reads the attached jobs store directly. It previously consulted `AnalysisSource.jobSnapshot`, which nothing ever populated, so every call returned zeros and a null success rate — indistinguishable from a queue that had genuinely done nothing.

Per-release health, oldest first. Empty until a release has been recorded.

Compare the running release against the previous one.

Null when nothing has been recorded yet; on a first deploy it returns a result whose `previousRelease` is null and whose caveats say so.

Analyse every non-ignored issue, most recent failure first.

Read-only access to an attached subsystem, for the engines that sample it.

Real work behind a guarded action. Only reached after the guard approves.

Who to record an audit entry against.

Read from `x-observe-actor` when the caller sends one, and otherwise stated as unknown. The dashboard is behind a single shared token, so the server has no way to tell two people holding that token apart — which means every entry used to say `dashboard_operator` and the audit log could not answer "who flushed the cache". The header is a self-declared label, not an identity: anyone with the token can put anything in it. It is useful for telling a CI job from a human, and worthless as proof. Anything that needs to attribute an action to a person needs real authentication, not this.

Position in the deterministic sampling cycle.

Decides whether a request's spans are recorded.

Called only for a span with no parent, so one roll covers a whole request: every span below it inherits the decision through the parent chain. Rolling per span would give a request with ten spans a chance of 0.1^10 of being recorded in full, which is not what "10% of requests" means. Not random sampling — a seedable one. A recorded trace is a sample you can read, and a real sample cannot be chosen after seeing the results.

Structured detail about the change.

Without it an entry says only *that* something happened: "member.updated" cannot answer which role someone moved from or to, which is the whole question an audit log gets consulted for. Optional, so callers with nothing to add are not pushed into inventing a value.

"fixed" uses `slowQueryThresholdMs` as an absolute number.

"adaptive" treats it as a multiple of the query's own rolling p95, so a table whose queries normally take 400ms does not flag every one of them and a table that normally takes 5ms still gets caught at 50ms.

Window used for adaptive thresholds and baselines. Default 15m.

Service level objectives, evaluated and reported on the dashboard.

Each needs real traffic to mean anything — an objective with no samples reports `no-data` rather than a flattering 100%.

Share of requests to trace, from 0 to 1.

Defaults to 1, which records every span. At 0.1, roughly one request in ten gets a span, and the rest record nothing. A decision made upstream wins: if an incoming `traceparent` header says the request was not sampled, its spans are not sampled either, whatever this is set to. That keeps a sampled caller from silently losing its trace, and an unsampled one from flooding this service.