wide_events 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c53fd3a4d33b817af708d0675bfa0b8047e2487a354d62cfb9e3c915b9c3472
-  data.tar.gz: 747298c60ca63d3a90db33abbf69d430e20a67d5037f79dcbf6d018ab5c86cb4
+  metadata.gz: 861efab741f9c9c6445d2c5f877e08c6f7da36e01254719191d1976baaff398b
+  data.tar.gz: d2f7efdca7e96cd0f4d65589014ab0a137bde8ce22c1b3edd9bc15dd21425606
 SHA512:
-  metadata.gz: d54b65bd07d6294109efb49020299da91aeb040000c42841a175f1b7af3e7fb5a6989971fee3fae5a57f8c0d2c5692572cd08bd4fb978c5798cb7ce9ce98783f
-  data.tar.gz: e2a3a0d2d6400b1c1cd951c3f6c71c059ecc0cd2b67342beba43901a8ca30929b98ecafe5cab47994e0c3a5153b9773f186670a73ef7eb13894fff40bd9055f3
+  metadata.gz: 49017796cabf1aea3026d39049e8ffdd085b9806e81574797cecc14e2e2c46502db6e7a0f8a37c44c26cc78f86f4d71d29f5db2576108970bee290c76dad39ba
+  data.tar.gz: 14201839ae140bb2f4a35bef52c581a95b9e6a0939db7a16b12feea7a8ac8cdf46f449564720829df689b63eaf0c198d268448498fac70f5955073aed4bc84e0

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v0.1.3 (2026-08-03)
+
+- README links to the docs are absolute GitHub URLs, so they work on
+  rubygems.org (relative links 404 there).
+- The install generator adds the registry-enforcement teardown to
+  `test/test_helper.rb`, and `capture_wide_events` temporarily enables
+  instrumentation while restoring the previous enabled state and sink.
+- Documentation and bundled agent skills clarify privacy handling, unnamed
+  exception queries, request/job timing, and one-generation-per-event examples.
+
 ## v0.1.2 (2026-08-03)
 
 - README "In production" section and `docs/production-example.md`: an

data/README.md

@@ -5,9 +5,9 @@
 
 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.
+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, and every question becomes one query against storage you run. ClickHouse with HyperDX is a proven pairing (both open source); any OTLP backend works. If you'd rather not run tracing, the log sink emits one JSON event per request.
 
-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.
+That format matters more now that agents build with you. Telemetry stops being something humans only glance at and becomes something software queries repeatedly: an agent can instrument a feature, deploy it, and verify it in production. One row per request is a dense way to feed production behavior back into a context window, and owning the storage avoids metered per-event and per-query observability fees.
 
 ## Install
 
@@ -86,7 +86,7 @@ With the endpoint set, wide events enable themselves: the railtie inserts the mi
 - `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`
 
-A request and the jobs it enqueues are separate units of work: the request's wide event records the enqueue inside its timings, and each job execution emits its own event carrying `job.queue_latency_ms` (time spent waiting in the queue), so queue pressure is visible per job, not smeared into request latency.
+A request and the jobs it enqueues are separate units of work. Synchronous enqueue work contributes to the request's total duration; each job execution emits its own event carrying `job.queue_latency_ms` (time spent waiting in the queue), so queue pressure is visible per job rather than folded into request latency.
 
 ## Adding your own attributes
 
@@ -95,7 +95,7 @@ WideEvent.set("report.id" => report.id, "report.format" => "pdf")
 WideEvent.phase("pdf_render") { render_pdf }         # -> pdf_render.duration_ms
 ```
 
-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.
+Attribute writes are safe no-ops outside a unit of work; `phase` still executes and returns the wrapped block. Telemetry failures never raise into app code, so a telemetry bug cannot fail a request or job.
 
 Errors come in two shapes, and the difference is the point:
 
@@ -107,7 +107,7 @@ rescue Vendor::ApiError => e
 # Unhandled: any exception that escapes gets error: true with NO slug, automatically
 ```
 
-That makes `error = true AND exception.slug IS NULL` a standing query: every row is a failure nobody wrote a rescue for, which is a permanent, prioritized to-do list of rescues worth instrumenting.
+Filtering for `error = true`, a missing `exception.slug`, and a present `exception.type` isolates exception paths that escaped without a named handled failure. Treat the results as a prioritized investigation queue; add a rescue and `error!` only when handling the exception is intentional.
 
 ## The registry is a schema, not a wiki page
 
@@ -195,8 +195,9 @@ WideEvent.configure do |config|
     "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
+  # Optional overrides; defaults detect Solid Queue recurring executions and report via OpenTelemetry.handle_error:
+  # config.scheduled_job_detector = ->(job) { MyApp.scheduled_job?(job) }
+  # config.error_handler = ->(exception, message) { Rails.error.report(exception, context: { message: message }) }
 end
 ```
 
@@ -204,7 +205,7 @@ Log sink notes: events go to `config.logger` (or `Rails.logger`) at info level a
 
 ## Querying: ClickHouse + HyperDX
 
-[docs/clickhouse-hyperdx.md](docs/clickhouse-hyperdx.md) has a local quickstart (one container) and a query cookbook. The flavor:
+[docs/clickhouse-hyperdx.md](https://github.com/adammiribyan/wide_events/blob/main/docs/clickhouse-hyperdx.md) has a local quickstart (one container) and a query cookbook. The flavor:
 
 ```sql
 SELECT SpanAttributes['http.route.controller'] AS controller,
@@ -218,11 +219,11 @@ GROUP BY controller ORDER BY p50_ms DESC LIMIT 15
 
 ## In production
 
-Wide Events was extracted from a multi-tenant Rails app subject to healthcare privacy rules, where it runs in staging and production today: one row per request and job execution, exported over OTLP into self-hosted ClickStack. A request that runs a hybrid search and drafts a reply with an LLM still lands as one event, carrying the account, the feature flags evaluated, search quality (semantic hits kept, top cosine similarity), the model, tokens, latency, and cost, the Postgres query count, and an error slug for anything rescued along the way. [docs/production-example.md](docs/production-example.md) shows a full anonymized event, the instrumentation patterns behind it, and two standing queries taken from that deployment.
+Wide Events was extracted from a multi-tenant Rails app subject to healthcare privacy rules, where it runs in staging and production today: one row per request and job execution, exported over OTLP into self-hosted ClickStack. A request that runs a hybrid search and drafts a reply with an LLM still lands as one event, carrying the account, the feature flags evaluated, search quality (semantic hits kept, top cosine similarity), the model, tokens, latency, and cost, the Postgres query count, and an error slug for anything rescued along the way. [docs/production-example.md](https://github.com/adammiribyan/wide_events/blob/main/docs/production-example.md) shows a full anonymized event, the instrumentation patterns behind it, and two standing queries taken from that deployment.
 
 ## 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.
+Flat keys, dot namespaces, snake_case leaves. Durations end in `_duration_ms`, counts in `_count`, booleans read as assertions, timestamps serialize to RFC 3339. Apply your deployment's privacy policy to every identifier: opaque IDs are preferable to names or emails but should still be registered as `pii: opaque_id`. Exclude request params and free text, or flag them as `pii: review` for explicit handling.
 
 ## Development
 

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

@@ -28,13 +28,17 @@ module WideEvents
         if content.match?(%r{require "rails/test_help"\n}) && content.match?(/class TestCase\n/)
           inject_into_file "test/test_helper.rb", "require \"wide_event/test_helper\"\n",
             after: %r{require "rails/test_help"\n}
-          inject_into_file "test/test_helper.rb", "    include WideEvent::TestHelper\n",
+          inject_into_file "test/test_helper.rb", <<~RUBY.indent(4),
+            include WideEvent::TestHelper
+            teardown { assert_registered_wide_event_attributes }
+          RUBY
             after: /class TestCase\n/
         else
           say_status :skip, "test/test_helper.rb (not found or unrecognized) - wire the test helper manually:", :yellow
           say <<~MSG
                 require "wide_event/test_helper"   # after rails/test_help
                 include WideEvent::TestHelper      # inside ActiveSupport::TestCase
+                teardown { assert_registered_wide_event_attributes }
           MSG
         end
       end

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

@@ -5,7 +5,7 @@ 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.phase("pdf_render") { render_pdf }` 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

data/lib/wide_event/test_helper.rb

@@ -29,17 +29,21 @@ module WideEvent
       attrs
     end
 
-    # Swaps the sink for an in-memory one for the duration of the block and
-    # returns every wide event flushed inside it. Use around code that runs
-    # its own unit of work (jobs, full request dispatch).
+    # Enables instrumentation and swaps the sink for an in-memory one for the
+    # duration of the block, restoring both settings afterward. Returns every
+    # wide event flushed inside it. Use around code that runs its own unit of
+    # work (jobs, full request dispatch).
     def capture_wide_events(&block)
       original = WideEvent.config.sink
+      original_enabled = WideEvent.config.enabled
       sink = Sinks::Memory.new
       WideEvent.config.sink = sink
+      WideEvent.config.enabled = true
       block.call
       sink.events
     ensure
       WideEvent.config.sink = original
+      WideEvent.config.enabled = original_enabled
     end
 
     # Fails if strict mode saw any attribute that isn't declared in the

data/lib/wide_event/version.rb

@@ -1,3 +1,3 @@
 module WideEvent
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/skills/debugging-with-wide-events/SKILL.md

@@ -54,14 +54,15 @@ before reaching for logs or the trace waterfall.
 
 ## Standing queries
 
-- **Uninstrumented failures**: `error = 'true' AND SpanAttributes['exception.slug'] = ''`:
-  failures nobody wrote a rescue for. Each row is a candidate `error!` call;
-  fixing them is normal instrumentation work (see the
+- **Unnamed exception paths**: `SpanAttributes['error'] = 'true' AND
+  SpanAttributes['exception.slug'] = '' AND SpanAttributes['exception.type'] != ''`:
+  exceptions that escaped without a named handled failure. Investigate each
+  path; add a rescue and `error!` only when handling it is intentional (see the
   instrumenting-wide-events skill).
 - **Expected-error drift**: count by `exception.slug` week over week; a
   slug trending up is a quiet regression.
 - **Query-count outliers**: max `stats.postgres_query_count` per route; the
-  top entries are N+1s with names and account ids attached.
+  top entries are N+1 candidates with route names and account IDs attached.
 - **Cold starts**: correlate latency with `uptime_sec_log10` to separate
   deploy warm-up from real regressions.
 

data/skills/instrumenting-wide-events/SKILL.md

@@ -13,8 +13,8 @@ knows: the domain nouns.
 
 ## The API
 
-All calls are safe no-ops outside a request/job and never raise into app
-code: instrument freely.
+Attribute writes are safe no-ops outside a request/job; `phase` still executes
+and returns its block. Telemetry failures never raise into app code.
 
 ```ruby
 # Flat attributes, merged into the current event
@@ -40,14 +40,15 @@ handle.
 - 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_chars: 2140`, never the note text.
+- Sizes and counts over raw content: `note.body_char_count: 2140`, never the note text.
 
 ## PII policy
 
-Opaque ids (user id, account id) are fine. Names, emails, free-text user
-input, and request params are not. If an attribute could quote user input,
-mark it `pii: review` in the registry and expect it to be scrubbed or
-excluded from forwarding.
+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.
 
 ## The registry is the contract
 
@@ -66,8 +67,8 @@ Keys containing `*` are globs for dynamic families (`feature_flag.*`). With
 `config.strict = true` in the test environment, the suite records undeclared
 attributes; `assert_registered_wide_event_attributes` fails on them. Run
 `rake wide_events:registry:docs` if this app generates the human-readable
-registry doc, and never rename a shipped attribute without a reason -
-renames orphan historical data.
+registry doc, and never rename a shipped attribute without a reason—renames
+orphan historical data.
 
 ## Prove it in tests
 
@@ -82,7 +83,7 @@ end
 ```
 
 For code that runs its own unit of work (jobs, full request dispatch), use
-`capture_wide_events { ... }` and assert on the returned events.
+`capture_wide_events { perform_work }` and assert on the returned events.
 
 ## Checklist for any instrumentation change
 
@@ -90,4 +91,4 @@ For code that runs its own unit of work (jobs, full request dispatch), use
 2. New rescue blocks that swallow errors call `error!` with a unique static slug.
 3. Every new attribute has a registry entry in the same change.
 4. A test asserts the attribute is set (`assert_wide_event`).
-5. No PII beyond opaque ids; anything questionable is flagged `pii: review`.
+5. Opaque IDs are declared `pii: opaque_id`; anything questionable is flagged `pii: review`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wide_events
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Adam Miribyan