instrumenting-wide-events

Instrumenting wide events

Every HTTP request and job execution in this app emits one flat telemetry event: the OTel root span, marked main = true (or one JSON log line with the :log sink). The gem records the generic attributes (route, status, timings, query counts, cache hits). Your job is the attributes only the app knows: the domain nouns.

The API

Attribute writes are safe no-ops outside a request/job; phase still executes and returns its block. Telemetry failures never raise into app code.

# Flat attributes, merged into the current event
WideEvent.set("report.id" => report.id, "report.format" => "pdf")

# Time a block into <name>.duration_ms (returns the block's value)
WideEvent.phase("pdf_render") { render_pdf }

# Mark a handled failure in a rescue block
rescue Api::ClientError => e
  WideEvent.error!(slug: "err-vendor-user-not-found", exception: e, expected: true)

error! slugs are static kebab-case string literals, unique across the app, prefixed err-. Never interpolate into a slug. Unhandled exceptions get error: true with NO slug automatically: that absence is the standing "instrument this rescue" query, so don't fake slugs for paths you didn't handle.

Naming conventions

• Flat keys, dot namespaces, snake_case leaves: report.page_count, not reportPageCount or nested hashes.
• Durations end in _duration_ms (float milliseconds). Counts end in _count.
• Booleans read as assertions: report.cached, not report.cache_status.
• Timestamps are RFC 3339 strings (pass a Time; the gem serializes it).
• Sizes and counts over raw content: note.body_char_count: 2140, never the note text.

PII policy

Apply the deployment's privacy policy to every identifier. Opaque user and account IDs are preferable to names or emails, but still declare them as pii: opaque_id. Exclude free-text user input and request params. If an attribute could quote user input, mark it pii: review in the registry and expect it to be scrubbed or excluded from forwarding.