Skip to content

CONCEPT Cited by 1 source

Actor-tagged error

An actor-tagged error is an error occurrence captured in an observability system together with a tag identifying the principal (authenticated user, service account, internal tool, API key, tenant) that originated the request which triggered the error. The tag is attached at the point where the request is authenticated — not at the point where the error is raised — so every downstream error event, including database-layer errors that have no direct view of the caller, inherits the actor identity.

What it solves

The classic debugging problem for intermittent production errors is correlation across layers: the error is raised in the database (or a library, or a remote service) at a point where the original caller's identity has been stripped by several request hops. To associate the error with a caller, the engineer has to join error logs with request logs on a request ID, or inspect session state, or manually grep for temporal co-incidence.

An actor-tagged error short-circuits this: the caller identity is stored on the error itself, alongside the timestamp and the normalised SQL (or equivalent operation identifier). Opening the error-occurrences view shows {timestamp, normalised_sql, actor, other_tags} triples directly — no cross-system join required.

Canonical disclosure

PlanetScale's Query Insights implements this verbatim for database errors: "we tag all queries from authenticated requests with information about the actor, it was easy to look them up and determine that an internal tool was issuing multiple password create requests in parallel" (Source: sources/2026-04-21-planetscale-debugging-database-errors-with-insights).

The concrete debugging sequence Rafer Hazen walks through hinges on two observations visible directly in the error-occurrences page:

  1. "Occurrences of these errors come in small batches with nearly identical timestamps" — the timestamps (already on each error) reveal temporal clustering, hypothesising a concurrency bug.
  2. "The actor tag for each batch of errors is always the same" — the actor tag reveals that one caller (not organic user traffic) is responsible.

The combination turns a cross-request correlation problem (which user / service / request triggered these errors?) into a visual signal in the error table. No custom instrumentation, no log joins, no request-ID plumbing — the actor tag captured at query-execution time propagates through to the error at no additional engineering cost.

Why this belongs on the query-observability layer, not

the application layer

Application-layer error handlers could capture the actor themselves — every web framework has a current_user or equivalent in request scope. But in practice:

  • Many errors are raised by library code (ORM validations, HTTP clients, serialisers) that have no knowledge of application authentication state.
  • Errors raised at the database layer (ActiveRecord::RecordNotUnique, constraint violations, deadlocks, statement timeouts) may or may not propagate to the application depending on retry logic; those that don't propagate escape application-layer logging entirely.
  • Application-layer logging requires per-framework, per-library instrumentation — an eternal maintenance tax.

Capturing the actor tag at the query layer — via SQLCommenter-style comment attachment to every authenticated query — makes the attribution independent of where the error is raised. The database driver, the connection pool, or the managed-database service sees every query (and every query-result, including errors) and can record the tag uniformly.

Relationship to SQLCommenter

PlanetScale's actor tag is a specific application of the broader SQLCommenter convention — SQL comments carrying structured metadata (/* key=value, key2=value2 */) attached to every query the application issues. The comment is passed through the database protocol as a no-op on the query, but observable tools (Insights, Datadog DBM, pganalyze) parse the comment and attach the tags to their per-query aggregation. Actor tagging is the most consistently load-bearing of these tags because authentication is a first-class app-layer concern that every framework already computes — making the comment trivially populated for free.

Capture-threshold caveat

Insights documents a tail-capture threshold for tag storage: "to associate tags, a query pattern must have had at least one query that took more than 1 second, read more than 10k rows, or resulted in an error." Cheap-fast-successful queries are pattern-aggregated without per-occurrence tags to keep storage bounded; the interesting tail (slow / heavy / failing) is captured with tags intact. This is a deliberate economics trade-off: tag storage scales with interesting queries, not total query volume, while still giving debuggers full-fidelity actor attribution on the error path.

The threshold applies to queries; all errors — by virtue of being errors — are captured with tags intact.

Distinct from

  • concepts/audit-trail — audit trails are authoritative append-only records of actions taken for compliance and forensics; actor-tagged errors are observability breadcrumbs for debugging. An audit trail records what happened; an actor-tagged error records that a specific error class was raised while a specific actor was attempting something.
  • concepts/query-tag-filter — query-tag filter is the search primitive that makes actor-tagged errors (and other tagged queries) findable. A tag without a filter is data; a tag-filter turns it into a signal.

Seen in

Last updated · 347 distilled / 1,201 read