@lunora/observability is the telemetry layer extracted out of @lunora/do: the
in-memory ring buffers behind the Studio panels, the durable per-shard tables that
survive hibernation, and the folding logic that turns raw events into what an
operator reads.
Like the engine, it is host-neutral: it takes a SqlExec and plain event
objects. @lunora/do wires it into ctx.log / ctx.trace / ctx.metrics and
the __lunora_admin__ read RPCs, so an app gets it without importing it. To use
the helpers directly, import them from the package:
import { recordFunctionMetric, readFunctionMetrics } from "@lunora/observability";What it provides
| Area | What it does |
|---|---|
| Logs | LogBuffer ring + durable request log; ctx.log lines and synthetic sources |
| Traces | SpanBuffer + foldTraces: groups spans by trace, nests by parent, offsets from the root |
| Metrics | MetricBuffer for the live readout, metric-history for the durable minute-bucketed series |
| Function stats | function-metrics: durable per-function counters, latency, conflicts, and scan attribution |
| Query insights | query-metrics: normalized statements, slow-query buckets |
| Issues | error grouping over @lunora/fingerprint, plus triage state |
| Issue explainer | explainIssue: grounds a folded issue in the error catalog, optionally rewritten by Workers AI |
| Auth & security | auth-metrics, security-audit |
| Correlation | database-telemetry, storage-correlation, trace-context |
API
The entries below cover the main exports. The full list, including helpers and
table-name constants, is in api-snapshots/observability.api.md.
LogBuffer
Type: class
In-memory ring of ctx.log lines for one Durable Object instance. It resets on
hibernation. Use push, entries, clear, and read size and dropped.
SpanBuffer
Type: class
In-memory ring of spans for one instance, for the Traces panel. hasTrace(traceId)
reports whether a trace is still buffered.
MetricBuffer
Type: class
In-memory aggregation of ctx.metrics.* measurements for one instance. It folds
measurements into aggregates rather than keeping raw samples.
foldTraces(spans, limit?)
Type: (spans: ReadonlyArray<SpanEvent>, limit?: number) => FoldedTraces
Groups a flat span list by trace, nests spans by parent, and offsets each span from its trace root.
recordFunctionMetric(sql, input) and readFunctionMetrics(sql)
Type: (sql: SqlExec, input: RecordFunctionMetricInput) => void and
(sql: SqlExec) => FunctionCallStat[]
Write and read the durable per-function counters and latency aggregates. The data survives hibernation.
recordQueryMetric(...) and readQueryInsights(sql, rangeMs, now?)
Type: (sql: SqlExec, rawSql: string, durationMs: number, rowsRead: number, rowsWritten: number, now?: number, execCount?: number) => void
and (sql: SqlExec, rangeMs: number, now?: number) => QueryInsightsResult
Record one SQL statement, normalized to its text with literal values replaced, and read the query insights over a time range.
recordAuthEvent(sql, input) and readAuthMetrics(sql)
Type: (sql: SqlExec, input: RecordAuthEventInput) => void and
(sql: SqlExec) => AuthMetrics
Record an auth attempt or failure and read the failure rate. Attempts are kept in
60-second buckets (AUTH_METRICS_BUCKET_MS), and the table keeps 1440 buckets
(AUTH_METRICS_BUCKET_RETENTION).
appendRequestLogEntry(sql, entry, options?) and readRequestLog(sql, options?)
Type: (sql: SqlExec, entry: AppendRequestLogEntry, options?: RequestLogWriteOptions) => void
and (sql: SqlExec, options?: ReadRequestLogOptions) => RequestLogEntry[]
Append one row per function dispatch to the durable request log and read the rows back.
readMetricHistory(sql, options?)
Type: (sql: SqlExec, options?: { maxSeries?: number; sinceMs?: number }) => MetricHistoryResult
Read the durable per-minute series for ctx.metrics.*. Each bucket is 60 seconds
(METRIC_HISTORY_BUCKET_MS).
readErrorIssues(sql, options?)
Type: (sql: SqlExec, options?: ReadIssuesOptions) => ErrorIssue[]
Read the error issues that the request log groups by fingerprint.
explainIssue(binding, args, options?)
Type: (binding: unknown, args: Record<string, unknown>, options?: { defaultModel?: string }) => Promise<ExplainIssueResult>
Explain an issue from the error catalog. binding is the Workers AI binding
(env.AI) and can be unknown, because the function checks its shape. When the
binding is missing, the call returns the degraded: true result. defaultModel
defaults to DEFAULT_EXPLAIN_ISSUE_MODEL, which is
@cf/meta/llama-3.3-70b-instruct-fp8-fast.
buildSecurityAudit(rawEnv, options)
Type: (rawEnv: unknown, options: { dev: boolean }) => SecurityAuditResult
Build the security audit from the environment bindings. Each finding has a
severity (error, warning or info).
Two design notes
Durable and in-memory are different questions. The ring buffers answer "what
has happened since this instance woke", which is what a live panel wants and what
resets on a cold start. The reserved __lunora_* tables answer "what has happened
to this shard", which is what an operator wants and what has to survive
hibernation. Most areas ship both, and the read paths create their tables
defensively so a panel opened before any traffic returns empty rather than
throwing.
Everything caller-supplied is capped. A functionPath is attacker-reachable
(an unregistered dispatch still records under the name the caller supplied), so the
accumulator caps distinct paths, and the read paths clamp rows so a bloated table
cannot materialize into a Durable Object's ~128MB isolate. The issue explainer
caps every field that reaches a model prompt and fences the untrusted error report
inside an explicit delimiter the system prompt names as a data boundary.
Degradation is the default
The explainer never fails a call: with no AI binding, a model error, or a
timeout it returns a degraded: true result carrying the grounded catalog hint, so
the client always has something to render. The AI layer is additive, never the
only help.