Canonical Wide Events

A canonical wide event describes one completed unit of work with the context needed to understand its outcome. Instead of emitting a trail of disconnected messages for “request started,” “database called,” and “request finished,” the application records one request outcome containing route, account, release, duration, status, and categorized failure context.

“Wide” means the event can carry many useful fields. It does not mean copying every object in memory.

Start with the unit of work

Useful event boundaries include:

• an API request completed or timed out
• a job reached success or a terminal failure
• a webhook was processed, retried, or deduplicated
• an agent run completed, failed, or exceeded a safety limit
• an account reached an activation or billing milestone

Build the event over the life of the operation and emit it once the final outcome is known.

await telemetry.log("api_request_completed", {
  route_template: "/api/projects/:id/sync",
  method: "POST",
  status_code: 503,
  status: "failed",
  error_type: "dependency_timeout",
  latency_ms: 8420,
  dependency: "billing_database",
  request_id: requestId,
  team_id: teamId,
  release: process.env.APP_RELEASE,
});

Preserve dimensions future questions need

Include stable categories and identifiers that support filtering, grouping, or correlation. High-cardinality fields such as request IDs and account IDs are valuable for investigation even when they are poor chart groupings.

Record explicit units, normalized route templates, deployment context, and the denominator fields required for rates. An error count without total requests cannot produce a meaningful error rate.

Keep diagnostics proportional

A wide event complements traces and detailed diagnostic logs; it does not need to reproduce them. Attach a trace or correlation ID when deeper evidence lives elsewhere. Prefer a controlled error_type to a raw stack trace and a route template to a full URL.

Do not include authorization headers, cookies, request bodies, raw prompts, webhook payloads, or arbitrary customer content.

Validate with SQL

The event is complete when it answers its intended questions with plausible SQL, not when it contains the most fields. Exercise success, failure, retry, and timeout paths, inspect sample rows, and run the first rate or latency query.

Continue with structured events versus text logs, high-cardinality fields, and the SQL recipe library.