wide_events 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 60fd90a80072a4f375595529b63b5c739751de76d92d7e29ff1d8581ae6b5a07
+  data.tar.gz: 6656514b71043fa80493946446f19582d1a32fe63799f4f7a04e9f67b2cd595f
+SHA512:
+  metadata.gz: 43721569390e303660bde87aae8317fe320cd3c9722f33ec0a49e6bebc180258c5536e1596181653bc3302b4010fba56153b70c0129c3c5f458e89fbb055d6e2
+  data.tar.gz: 587ec94b148be767437f9d0d126c0ebd321ae5f91db31ef4236ff75cad1d39c5572f8e44d3791a410420b48c7304143260d51049e43607afb2d0573d220ab82b

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## v0.1.0 (2026-08-03)
+
+First release, extracted from a production Rails app.
+
+- Wide-event accumulator (`set`, `phase`, `error!`, `count`) with a
+  never-raise contract and per-request/per-job isolation.
+- Rack middleware and ActiveJob instrumentation, wired by a railtie.
+- Sinks: OTel root span (default), JSON log lines, in-memory (tests).
+- Span counter: child-span rollups into `stats.*` (configurable scope map).
+- Notification subscribers: `db.duration_ms`, `view.duration_ms`, capped
+  `cache.*` hit/miss booleans.
+- Attribute registry (`config/wide_event/registry.yml`): gem defaults,
+  glob entries, strict-mode tracking, `rake wide_events:registry:check`
+  and `rake wide_events:registry:docs`.
+- Test helpers: `assert_wide_event`, `capture_wide_events`,
+  `assert_registered_wide_event_attributes`.
+- Generators: `wide_events:install` (initializer, registry, AGENTS.md
+  section) and `wide_events:skills` (agent skills for writing and
+  querying instrumentation).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Miribyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# Wide Events
+
+One wide telemetry event per Rails request or job execution, in a database you own.
+
+Wide Events collects everything your app knows about each unit of work (route, user, account, build SHA, query counts, cache hits, feature flags, phase timings, errors) into one flat, high-cardinality event on the OpenTelemetry root span you already export. Every request becomes one row. Every question becomes one query against storage you run: ClickHouse with HyperDX on top is a proven pairing (both open source), any OTLP backend works, and a log-line sink emits one JSON event per request if you'd rather not run tracing at all.
+
+That format matters more now that agents build with you. Telemetry stops being something humans glance at and becomes something software queries in a loop: an agent that instruments a feature, deploys it, and verifies it in production will hit your observability stack fifty times before lunch. One row per request is the densest way to feed production behavior back into a context window, and owning the storage means the loop has no price per iteration.
+
+## Install
+
+```ruby
+# Gemfile
+gem "wide_events"
+```
+
+```bash
+bin/rails generate wide_events:install   # initializer + attribute registry + AGENTS.md section
+bin/rails generate wide_events:skills    # agent skills into .claude/skills/
+```
+
+Wide events turn on wherever `OTEL_EXPORTER_OTLP_ENDPOINT` is set. Dev and test pay nothing.
+
+## What you get per event
+
+The gem records the generic attributes on every request and job:
+
+- `http.request.id`, `http.response.status_code`, `http.route.controller`, request body size, parsed `user_agent.*`
+- `db.duration_ms` and `view.duration_ms` (Rails' own measurements)
+- `stats.postgres_query_count` / `_duration_ms` and `stats.http_call_count` / `_duration_ms`, rolled up from OTel child spans (scope map is configurable)
+- `cache.<prefix>` hit/miss booleans, capped per event
+- `job.class`, `job.queue`, `job.queue_latency_ms`, `job.executions`, `job.scheduled` (Solid Queue recurring detection built in, detector pluggable)
+- `error`, `exception.type`, `exception.message`, `uptime_sec`, `main: true`
+
+Your code adds the parts only it knows:
+
+```ruby
+WideEvent.set("report.id" => report.id, "report.format" => "pdf")
+WideEvent.phase("pdf_render") { render_pdf }         # -> pdf_render.duration_ms
+WideEvent.error!(slug: "err-export-source-missing", exception: e, expected: true)
+```
+
+Every call is a safe no-op outside a unit of work and never raises into app code. A telemetry bug cannot fail a request or a job.
+
+"Something is slow" turns into "the reports route is slow for account 4218 on build f3a91c, and it's running 742 queries": one query in HyperDX for you, one SQL call for your agent.
+
+## The registry is a schema, not a wiki page
+
+Every attribute is declared in `config/wide_event/registry.yml`:
+
+```yaml
+report.format:
+  type: string
+  set_by: ReportsController#create
+  pii: none
+  notes: pdf or csv
+```
+
+The gem registers its own attributes by default; globs (`feature_flag.*`) cover dynamic families. With `config.strict = true` in the test environment, the suite records every undeclared attribute it sees, and `assert_registered_wide_event_attributes` fails on them. `rake wide_events:registry:check` validates the file; `rake wide_events:registry:docs` generates the human-readable registry doc from it, so documentation can't drift from reality.
+
+## Testing
+
+```ruby
+# test_helper.rb
+require "wide_event/test_helper"
+class ActiveSupport::TestCase
+  include WideEvent::TestHelper
+end
+```
+
+```ruby
+test "report rendering is instrumented" do
+  assert_wide_event("pdf_render.duration_ms", "report.format" => "pdf") do
+    Report.new(format: "pdf").render
+  end
+end
+
+test "job emits one wide event" do
+  events = capture_wide_events { ExportJob.perform_now }
+  assert_equal 1, events.length
+end
+```
+
+## Built for the agent loop
+
+`bin/rails generate wide_events:skills` installs two agent skills:
+
+- **instrumenting-wide-events**: the write path. Naming conventions, when to use `set` vs `phase` vs `error!`, the registry workflow, PII rules, test assertions.
+- **debugging-with-wide-events**: the read path. Symptom-to-query workflow against ClickHouse/HyperDX or JSON logs, plus the standing queries worth running: `error = true AND exception.slug IS NULL` is a permanent, queryable to-do list of rescues nobody instrumented.
+
+The install generator also appends a wide-events section to `AGENTS.md`, so every future session knows the instrumentation exists and how to extend it.
+
+## Configuration
+
+```ruby
+WideEvent.configure do |config|
+  config.enabled = ENV["OTEL_EXPORTER_OTLP_ENDPOINT"].present?  # default
+  config.sink = :otel               # :otel, :log, or any object responding to flush(attrs)
+  config.strict = Rails.env.test?   # track attributes against the registry
+  config.max_cache_attrs = 10
+  config.span_scopes = {            # OTel instrumentation scope -> stats.* name
+    "OpenTelemetry::Instrumentation::PG" => "postgres_query",
+    "OpenTelemetry::Instrumentation::Net::HTTP" => "http_call"
+  }
+  config.scheduled_job_detector = ->(job) { ... }  # default detects Solid Queue recurring executions
+  config.error_handler = ->(exception, message) { ... }  # default reports via OpenTelemetry.handle_error
+end
+```
+
+The railtie inserts the middleware directly below `ActionDispatch::Executor` (the executor clears the per-request store, so placement matters), instruments `ActiveJob::Base`, and wires the span counter and notification subscribers after your initializers run. Without Rails, call `WideEvent.install!` yourself after configuring the OpenTelemetry SDK.
+
+## Conventions
+
+Flat keys, dot namespaces, snake_case leaves. Durations end in `_duration_ms`, counts in `_count`, booleans read as assertions, timestamps serialize to RFC 3339. Opaque ids are fine; names, emails, and request params are not, and anything that could quote user input is flagged `pii: review` in the registry.
+
+Unhandled exceptions get `error: true` with no slug, deliberately: the missing slug marks the rescue you haven't instrumented yet.
+
+## Development
+
+```bash
+bin/setup                 # bundle install + appraisal gemfiles
+bundle exec rake test     # run the suite
+bin/rubocop               # lint (rubocop-rails-omakase)
+```
+
+The CI matrix runs the suite across Ruby 3.2 to 4.0 and Rails 7.1 to main via [Appraisal](https://github.com/thoughtbot/appraisal); run a specific combination locally with `BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake test`. Releases go out with `bin/release <version>`.
+
+## Requirements
+
+Ruby >= 3.2, Rails >= 7.1 (activesupport and rack are the only hard dependencies; opentelemetry-sdk and useragent are optional and detected at runtime).
+
+## License
+
+MIT.

data/lib/generators/wide_events/install/install_generator.rb

@@ -0,0 +1,26 @@
+require "rails/generators/base"
+
+module WideEvents
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        copy_file "initializer.rb", "config/initializers/wide_events.rb"
+      end
+
+      def create_registry
+        copy_file "registry.yml", "config/wide_event/registry.yml"
+      end
+
+      def add_agents_section
+        section = File.read(File.expand_path("templates/agents_md_section.md", __dir__))
+        if File.exist?(File.join(destination_root, "AGENTS.md"))
+          append_to_file "AGENTS.md", "\n#{section}"
+        else
+          create_file "AGENTS.md", section
+        end
+      end
+    end
+  end
+end

data/lib/generators/wide_events/install/templates/agents_md_section.md

@@ -0,0 +1,17 @@
+## Wide events
+
+Every HTTP request and job execution emits one flat telemetry event (the OTel
+root span, marked `main = true`). When you add or change a feature,
+instrument it:
+
+- `WideEvent.set("report.id" => report.id)` for domain attributes
+- `WideEvent.phase("pdf_render") { ... }` to time a block into `pdf_render.duration_ms`
+- `WideEvent.error!(slug: "err-report-source-missing", exception: e, expected: true)` in rescue blocks
+
+Naming: dot namespaces with snake_case leaves, durations end in
+`_duration_ms`, counts in `_count`, booleans read as assertions. Every new
+attribute must be declared in `config/wide_event/registry.yml` in the same
+change; the test suite fails on undeclared attributes. Assert instrumentation
+with `assert_wide_event` from `wide_event/test_helper`. See the
+`instrumenting-wide-events` skill for full conventions and
+`debugging-with-wide-events` for querying production.

data/lib/generators/wide_events/install/templates/initializer.rb

@@ -0,0 +1,11 @@
+WideEvent.configure do |config|
+  # Enabled wherever OTEL_EXPORTER_OTLP_ENDPOINT is set, flushing onto the
+  # OTel root span. Uncomment to emit JSON log lines instead (no tracing
+  # required):
+  # config.enabled = true
+  # config.sink = :log
+
+  # Track attributes against config/wide_event/registry.yml in tests; pair
+  # with assert_registered_wide_event_attributes to enforce the schema.
+  config.strict = Rails.env.test?
+end

data/lib/generators/wide_events/install/templates/registry.yml

@@ -0,0 +1,16 @@
+# Attributes your app sets on wide events, one entry per attribute. The gem's
+# own attributes (main, error, http.*, user_agent.*, job.*, stats.*, cache.*,
+# db/view durations, exception.*) are registered by default: declare only
+# what your code adds. Keys containing `*` are globs for dynamic attributes.
+#
+# Fields: type (string/integer/float/boolean, or a list), set_by, pii
+# (none/opaque_id/review), notes, forward (optional list of sinks that may
+# receive the attribute).
+#
+# Example:
+#
+# report.format:
+#   type: string
+#   set_by: ReportsController#create
+#   pii: none
+#   notes: pdf or csv

data/lib/generators/wide_events/skills/skills_generator.rb

@@ -0,0 +1,20 @@
+require "rails/generators/base"
+
+module WideEvents
+  module Generators
+    # Copies the agent skills shipped with the gem into .claude/skills/ so
+    # coding agents pick up the instrumentation and debugging conventions.
+    class SkillsGenerator < Rails::Generators::Base
+      SKILLS_ROOT = File.expand_path("../../../../skills", __dir__)
+
+      source_root SKILLS_ROOT
+
+      def copy_skills
+        Dir[File.join(SKILLS_ROOT, "*", "SKILL.md")].sort.each do |path|
+          name = File.basename(File.dirname(path))
+          copy_file File.join(name, "SKILL.md"), ".claude/skills/#{name}/SKILL.md"
+        end
+      end
+    end
+  end
+end

data/lib/wide_event/configuration.rb

@@ -0,0 +1,63 @@
+module WideEvent
+  class Configuration
+    # Reports through OTel's error handler when it's loaded; silent otherwise.
+    DEFAULT_ERROR_HANDLER = lambda do |exception, message|
+      if defined?(OpenTelemetry) && OpenTelemetry.respond_to?(:handle_error)
+        OpenTelemetry.handle_error(exception: exception, message: "wide_event #{message}")
+      end
+    end
+
+    # Recurring (scheduled) Solid Queue executions have a RecurringExecution
+    # row pointing at the underlying job. One indexed query per execution.
+    SOLID_QUEUE_DETECTOR = lambda do |job|
+      return false unless defined?(SolidQueue::RecurringExecution)
+      job.provider_job_id.present? && SolidQueue::RecurringExecution.exists?(job_id: job.provider_job_id)
+    rescue StandardError
+      false
+    end
+
+    attr_accessor :enabled, :max_cache_attrs, :span_scopes, :strict,
+                  :logger, :error_handler, :scheduled_job_detector
+    attr_reader :sink, :registry_path
+
+    def initialize
+      @enabled = !ENV["OTEL_EXPORTER_OTLP_ENDPOINT"].to_s.empty?
+      @sink = :otel
+      @resolved_sink = nil
+      @max_cache_attrs = 10
+      @span_scopes = {
+        "OpenTelemetry::Instrumentation::PG" => "postgres_query",
+        "OpenTelemetry::Instrumentation::Net::HTTP" => "http_call"
+      }
+      @strict = false
+      @registry_path = nil
+      @registry = nil
+      @logger = nil
+      @error_handler = DEFAULT_ERROR_HANDLER
+      @scheduled_job_detector = SOLID_QUEUE_DETECTOR
+    end
+
+    def sink=(value)
+      @sink = value
+      @resolved_sink = nil
+    end
+
+    def resolved_sink
+      @resolved_sink ||= case @sink
+      when :otel then Sinks::OtelSpan.new
+      when :log then Sinks::LogLine.new(logger)
+      else @sink
+      end
+    end
+
+    def registry_path=(path)
+      @registry_path = path
+      @registry = nil
+    end
+
+    def registry
+      return nil if @registry_path.nil?
+      @registry ||= Registry.load(@registry_path)
+    end
+  end
+end

data/lib/wide_event/job_instrumentation.rb

@@ -0,0 +1,55 @@
+require "active_support/concern"
+
+module WideEvent
+  # One wide event per job execution: the job-shaped unit of work. Included
+  # into ActiveJob::Base by the railtie; include it manually in ApplicationJob
+  # when not using the railtie.
+  #
+  # Known semantics: exceptions later swallowed by retry_on/discard_on still
+  # mark this execution error=true: the wide event records that THIS attempt
+  # failed, which is accurate per-execution; roll up by job.id to judge the
+  # job.
+  module JobInstrumentation
+    extend ActiveSupport::Concern
+
+    included do
+      around_perform :wide_event
+    end
+
+    private
+
+    def wide_event(&block)
+      return block.call unless WideEvent.enabled?
+
+      WideEvent.with do |attrs|
+        enqueued = enqueued_at.is_a?(String) ? Time.iso8601(enqueued_at) : enqueued_at
+        WideEvent.set({
+          "main" => true,
+          "job.class" => self.class.name,
+          "job.queue" => queue_name,
+          "job.id" => job_id,
+          "job.executions" => executions,
+          "job.enqueued_at" => enqueued,
+          "job.queue_latency_ms" => enqueued ? ((Time.now - enqueued) * 1000).round : nil,
+          "job.scheduled" => wide_event_scheduled?
+        }.merge(WideEvent.uptime_attributes))
+        begin
+          block.call
+        rescue Exception => e
+          WideEvent.set("error" => true, "exception.type" => e.class.name,
+                        "exception.message" => e.message.to_s[0, 500])
+          raise
+        ensure
+          WideEvent.flush(attrs)
+        end
+      end
+    end
+
+    def wide_event_scheduled?
+      detector = WideEvent.config.scheduled_job_detector
+      detector ? detector.call(self) == true : false
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/wide_event/middleware.rb

@@ -0,0 +1,81 @@
+begin
+  require "useragent"
+rescue LoadError
+  # Optional: without the useragent gem only user_agent.original is set.
+end
+
+module WideEvent
+  # Opens the wide-event accumulator for each request and flushes it to the
+  # configured sink as the response unwinds. With the OTel sink, the flush
+  # target is the root span opened by OTel's Rack instrumentation at the top
+  # of the stack. Must be inserted BELOW ActionDispatch::Executor: the
+  # executor clears IsolatedExecutionState on completion, so above it the
+  # store would be gone before the flush. The railtie handles placement.
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return @app.call(env) unless WideEvent.enabled?
+
+      WideEvent.with do |attrs|
+        seed(env)
+        begin
+          status, headers, body = @app.call(env)
+          ex = env["action_dispatch.exception"]
+          WideEvent.set(
+            "http.response.status_code" => status.to_i,
+            "error" => status.to_i >= 500 || attrs["error"] == true || !ex.nil?
+          )
+          if ex
+            # Rendered by ActionDispatch::ShowExceptions before this
+            # middleware's rescue ever fires: error attrs WITHOUT a slug,
+            # same convention as the unhandled-exception path below.
+            WideEvent.set("error" => true, "exception.type" => ex.class.name,
+                          "exception.message" => ex.message.to_s[0, 500])
+          end
+          [ status, headers, body ]
+        rescue Exception => e
+          # Unhandled exception: error attrs WITHOUT a slug: the standing
+          # "instrument this rescue" query keys off the missing slug.
+          WideEvent.set("error" => true, "exception.type" => e.class.name,
+                        "exception.message" => e.message.to_s[0, 500])
+          raise
+        ensure
+          # Read at flush time, on every path (success AND unhandled
+          # exception): ActionDispatch::RequestId runs deeper in the stack
+          # and mutates env in place, so the id doesn't exist at seed time
+          # but does by the time any outcome unwinds back to here.
+          WideEvent.set("http.request.id" => env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"])
+          WideEvent.flush(attrs)
+        end
+      end
+    end
+
+    private
+
+    def seed(env)
+      WideEvent.set({
+        "main" => true,
+        "http.request.body_size" => env["CONTENT_LENGTH"]&.to_i
+      }.merge(user_agent_attributes(env["HTTP_USER_AGENT"])).merge(WideEvent.uptime_attributes))
+    end
+
+    def user_agent_attributes(ua)
+      return {} if ua.nil? || ua.empty?
+      return { "user_agent.original" => ua[0, 300] } unless defined?(UserAgent)
+
+      parsed = UserAgent.parse(ua)
+      {
+        "user_agent.original" => ua[0, 300],
+        "user_agent.browser" => parsed.browser,
+        "user_agent.browser_version" => parsed.version.to_s,
+        "user_agent.os" => parsed.os,
+        "user_agent.platform" => parsed.platform
+      }
+    rescue StandardError
+      { "user_agent.original" => ua[0, 300] }
+    end
+  end
+end

data/lib/wide_event/railtie.rb

@@ -0,0 +1,32 @@
+require "rails/railtie"
+
+module WideEvent
+  class Railtie < Rails::Railtie
+    # Below ActionDispatch::Executor on purpose: the executor clears
+    # IsolatedExecutionState on completion; above it the store would be gone
+    # before the flush. With OTel Rack instrumentation at the top of the
+    # stack, the flush still lands inside the root span.
+    initializer "wide_event.middleware" do |app|
+      app.middleware.insert_after ActionDispatch::Executor, WideEvent::Middleware
+    end
+
+    initializer "wide_event.active_job" do
+      ActiveSupport.on_load(:active_job) { include WideEvent::JobInstrumentation }
+    end
+
+    initializer "wide_event.registry" do |app|
+      path = app.root.join("config", "wide_event", "registry.yml")
+      WideEvent.config.registry_path ||= path.to_s if path.exist?
+    end
+
+    # After the app's own initializers, so the host's OpenTelemetry::SDK
+    # configuration (and any WideEvent.configure block) has already run.
+    config.after_initialize do
+      WideEvent.install! if WideEvent.enabled?
+    end
+
+    rake_tasks do
+      load File.expand_path("tasks/registry.rake", __dir__)
+    end
+  end
+end

data/lib/wide_event/registry/defaults.yml

@@ -0,0 +1,131 @@
+# Attributes the gem sets on every wide event. App attributes belong in the
+# app's own registry file (config/wide_event/registry.yml), which merges over
+# these entries.
+main:
+  type: boolean
+  set_by: wide_events
+  pii: none
+  notes: Marks the root span as a wide event. Query surface is `main = true`.
+error:
+  type: boolean
+  set_by: wide_events
+  pii: none
+  notes: Status >= 500, an unhandled exception, or an error! call.
+uptime_sec:
+  type: integer
+  set_by: wide_events
+  pii: none
+  notes: Process age at the time of the event.
+uptime_sec_log10:
+  type: float
+  set_by: wide_events
+  pii: none
+  notes: log10 of uptime_sec, for cold-start histograms.
+http.request.id:
+  type: string
+  set_by: wide_events
+  pii: none
+  notes: X-Request-Id / ActionDispatch request id.
+http.request.body_size:
+  type: integer
+  set_by: wide_events
+  pii: none
+http.response.status_code:
+  type: integer
+  set_by: wide_events
+  pii: none
+http.route.controller:
+  type: string
+  set_by: wide_events
+  pii: none
+  notes: Controller#action, from process_action.action_controller.
+user_agent.original:
+  type: string
+  set_by: wide_events
+  pii: none
+  notes: Capped at 300 chars.
+user_agent.browser:
+  type: string
+  set_by: wide_events
+  pii: none
+user_agent.browser_version:
+  type: string
+  set_by: wide_events
+  pii: none
+user_agent.os:
+  type: string
+  set_by: wide_events
+  pii: none
+user_agent.platform:
+  type: string
+  set_by: wide_events
+  pii: none
+db.duration_ms:
+  type: float
+  set_by: wide_events
+  pii: none
+  notes: Rails' own db_runtime measurement.
+view.duration_ms:
+  type: float
+  set_by: wide_events
+  pii: none
+  notes: Rails' own view_runtime measurement.
+"cache.*":
+  type: boolean
+  set_by: wide_events
+  pii: none
+  notes: Hit/miss per normalized cache key prefix, capped per event.
+"stats.*":
+  type: [integer, float]
+  set_by: wide_events
+  pii: none
+  notes: Per-dependency child span counts and total durations.
+job.class:
+  type: string
+  set_by: wide_events
+  pii: none
+job.queue:
+  type: string
+  set_by: wide_events
+  pii: none
+job.id:
+  type: string
+  set_by: wide_events
+  pii: none
+job.executions:
+  type: integer
+  set_by: wide_events
+  pii: none
+  notes: Retry count, 1 on the first attempt.
+job.enqueued_at:
+  type: string
+  set_by: wide_events
+  pii: none
+  notes: RFC 3339.
+job.queue_latency_ms:
+  type: integer
+  set_by: wide_events
+  pii: none
+job.scheduled:
+  type: boolean
+  set_by: wide_events
+  pii: none
+  notes: True for recurring/scheduled executions (Solid Queue detector by default).
+exception.slug:
+  type: string
+  set_by: app rescue sites via error!
+  pii: none
+  notes: Static kebab-case identifier. Absent on unhandled exceptions, by design.
+exception.type:
+  type: string
+  set_by: wide_events
+  pii: none
+exception.message:
+  type: string
+  set_by: wide_events
+  pii: review
+  notes: Capped at 500 chars. May quote user input (review before forwarding).
+exception.expected:
+  type: boolean
+  set_by: app rescue sites via error!
+  pii: none