Structured Logging Guide

Structured logging records an event as named fields instead of placing every detail in a sentence. A message such as checkout failed for account 42 after 812 ms is readable, but SQL has to parse it before it can group failures or calculate latency. A structured event stores event_name, account_id, status, error_type, and latency_ms separately.

Start with a question

Write down the operational or product question before choosing fields. “Which checkout step fails most often?” implies a stable step name, status, error category, and timestamp. “Which customers were affected?” also requires a safe account identifier. A field without a likely filter, group, calculation, or debugging use is probably noise.

Prefer one event at a meaningful boundary: a request completed, a job exhausted its retries, a webhook was deduplicated, or a user reached an activation milestone. Avoid emitting a different table for every branch of the same workflow. A consistent status field makes success and failure comparable.

await telemetry.log("checkout_completed", {
  checkout_version: "v2",
  account_id: account.id,
  status: "failed",
  error_type: "payment_declined",
  latency_ms: 812,
  attempt: 1,
});

Keep the contract stable

Use snake_case names, explicit units such as _ms and _bytes, and UTC timestamps. Store categories such as payment_declined, not the full exception text, when you want a reliable grouping dimension. Keep identifiers consistent across events so a request, account, release, or job can be followed through the system.

Do not silently change a field from a number to a string. If its meaning changes, add a version field or a new event contract. The event schema design guide explains naming, ownership, and evolution in more detail.

Protect sensitive data

Treat every new field as data that may appear in a query result, dashboard, or export. Do not send credentials, cookies, authorization headers, full request bodies, payment details, or raw prompts. Prefer internal identifiers and controlled categories over emails and free-form user content. Apply allowlists at the event construction boundary; redaction after ingestion is a fallback, not the primary control.

Verify the event

Exercise success, failure, timeout, and retry branches with synthetic data. Inspect the resulting table, confirm field types, and run the query that motivated the event. Then create a visualization or alert only after the result matches the business definition.

Continue with structured events versus text logs, redacting sensitive data, or copy a complete query from the SQL recipe library.