nestjs-otel 8.0.4-alpha.8 → 8.1.0

package/README.md

@@ -310,7 +310,9 @@ export class BookService {
 
 Wide events (also known as canonical log lines) emit one context-rich event per request, with attributes accumulated across the whole request lifecycle. See [A Practitioner's Guide to Wide Events](https://jeremymorrell.dev/blog/a-practitioners-guide-to-wide-events/) for the pattern.
 
-This library implements the pattern on top of OpenTelemetry: the `WideEventInterceptor` opens an attribute bag per request and, when the request finishes, flushes everything onto the span that was active when the request entered the interceptor (usually the root HTTP span created by your instrumentation). The `WideEventService` lets any provider enrich that bag from anywhere in the request's async call chain — no request-scoped injection needed.
+This library implements the pattern on top of OpenTelemetry: the `WideEventInterceptor` opens an attribute bag per request and, when the request finishes, flushes everything onto a single span — marking it with `nestjs_otel.wide_event = true` so you can filter wide-event spans in your backend. The `WideEventService` lets any provider enrich that bag from anywhere in the request's async call chain — no request-scoped injection needed.
+
+By default the attributes land on the best-available recording span at flush time (the HTTP root on Express / plain Fastify, or the active handler span when an instrumentation such as `@opentelemetry/instrumentation-nestjs-core` or `@fastify/otel` nests a span per request phase). To guarantee they land on the **trace root span** regardless of instrumentation nesting, register the [`WideEventSpanProcessor`](#targeting-the-root-span-wideeventspanprocessor).
 
 1. Register the interceptor globally:
 
@@ -368,10 +370,11 @@ export class CheckoutService {
 }
 ```
 
-All accumulated attributes land on the root span as a single wide event:
+All accumulated attributes land on a single span as one wide event:
 
 ```
-http_request
+GET /checkout
+├── nestjs_otel.wide_event: true
 ├── code.function.name: CheckoutController.checkout
 ├── user.id: u-123
 ├── cart.items: 3
@@ -384,7 +387,8 @@ http_request
 
 Notes:
 
-- The interceptor seeds `code.function.name` (`<Controller>.<handler>`) automatically and records `error.type`/`error.message` when the handler throws.
+- The flushed span is marked `nestjs_otel.wide_event = true`. This marker is set last, so a handler-provided field can never overwrite it.
+- The interceptor seeds `code.function.name` (`<Controller>.<handler>`) automatically and records `error.type`/`error.message` (plus `error.stack` when present) when the handler throws.
 - `WideEventService` methods are safe no-ops outside a request handled by the interceptor.
 - An async-context-aware context manager is required (the default with `NodeSDK` / `AsyncLocalStorageContextManager`), same as for tracing in general.
 
@@ -425,6 +429,28 @@ export class BooksService {
 }
 ```
 
+### Targeting the root span (`WideEventSpanProcessor`)
+
+Instrumentations like `@opentelemetry/instrumentation-nestjs-core` and `@fastify/otel` wrap each request phase (middleware, guard, handler) in its own span. As a result, the span active when the interceptor runs is a nested child, not the trace root — so by default the wide event lands on that child span (e.g. `AppController.handler`) rather than on the root `GET /route`.
+
+Register the `WideEventSpanProcessor` on your `NodeSDK` to make the interceptor flush onto the **local-root span** (the span with no in-process parent — normally the HTTP server span) instead:
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { WideEventSpanProcessor } from 'nestjs-otel';
+
+export const otelSDK = new NodeSDK({
+  spanProcessors: [
+    new WideEventSpanProcessor(),
+    new BatchSpanProcessor(traceExporter),
+  ],
+  // ...instrumentations, contextManager, etc.
+});
+```
+
+The processor only tracks which span is the local root per trace; it never exports spans, so keep your existing exporting processor in the list. It is optional — without it, wide events still flush onto the best-available recording span (see above), just not necessarily the trace root.
+
 ## Metric Service
 
 [OpenTelemetry Metrics](https://www.npmjs.com/package/@opentelemetry/api) allow a user to collect data and export it to metrics backend like Prometheus.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-otel",
-  "version": "8.0.4-alpha.8",
+  "version": "8.1.0",
   "description": "NestJS OpenTelemetry Library",
   "main": "lib/index.js",
   "typings": "lib/index",

package/.claude/settings.json

@@ -1,24 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "CMD=$(python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))\" 2>/dev/null || true); case \"$CMD\" in *grep*|*rg\\ *|*ripgrep*|*find\\ *|*fd\\ *|*ack\\ *|*ag\\ *)   [ -f graphify-out/graph.json ] &&   echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"MANDATORY: graphify-out/graph.json exists. You MUST run `graphify query \\\"<question>\\\"` before grepping raw files. Only grep after graphify has oriented you, or to modify/debug specific lines.\"}}'   || true ;; esac"
-          }
-        ]
-      },
-      {
-        "matcher": "Read|Glob",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "HIT=$(python3 -c \"import json,sys;d=json.load(sys.stdin);t=d.get('tool_input',d);s=(str(t.get('file_path') or '')+' '+str(t.get('pattern') or '')+' '+str(t.get('path') or '')).lower().replace(chr(92),'/');exts=('.py','.js','.ts','.tsx','.jsx','.go','.rs','.java','.rb','.c','.h','.cpp','.hpp','.cc','.cs','.kt','.swift','.php','.scala','.lua','.sh','.md','.rst','.txt','.mdx');sys.stdout.write('1' if 'graphify-out/' not in s and any(e in s for e in exts) else '')\" 2>/dev/null || true); if [ \"$HIT\" = 1 ] && [ -f graphify-out/graph.json ]; then echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"MANDATORY: graphify-out/graph.json exists. You MUST run graphify before reading source files. Use: `graphify query \\\"<question>\\\"` (scoped subgraph), `graphify explain \\\"<concept>\\\"`, or `graphify path \\\"<A>\\\" \\\"<B>\\\"`. Only read raw files after graphify has oriented you, or to modify/debug specific lines. This rule applies to subagents too \u2014 include it in every subagent prompt involving code exploration.\"}}'; fi || true"
-          }
-        ]
-      }
-    ]
-  }
-}

package/.claude/settings.local.json

@@ -1,20 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(cp tests/e2e/wide-events/wide-event.spec.ts /tmp/we.bak)",
-      "Bash(cp /tmp/we.bak tests/e2e/wide-events/wide-event.spec.ts)",
-      "Bash(graphify query *)",
-      "Bash(rtk npm *)",
-      "Bash(rtk jest *)",
-      "WebFetch(domain:jeremymorrell.dev)",
-      "WebFetch(domain:boristane.com)",
-      "WebFetch(domain:isburmistrov.substack.com)",
-      "Bash(rtk npx *)",
-      "Bash(rtk ls *)",
-      "Bash(rtk grep *)",
-      "Bash(rtk read *)",
-      "Bash(cd /Users/pragmaticivan/Code/pragmaticivan/nestjs-otel-prom-grafana-tempo)",
-      "Bash(rtk find *)"
-    ]
-  }
-}

package/.tmp_build.out

@@ -1,3 +0,0 @@
-go: cannot find main module, but found .git/config in /Users/pragmaticivan/Code/pragmaticivan/nestjs-otel
-	to create a module there, run:
-	go mod init

package/graphify-out/.graphify_labels.json

@@ -1,12 +0,0 @@
-{
-  "0": "Metric Decorators & Data",
-  "1": "Span Decorator & Tests",
-  "2": "Module Bootstrap & Tracing",
-  "3": "Wide Events",
-  "4": "Traceable Decorator",
-  "5": "Counter Decorators & Metadata Utils",
-  "6": "Test Service Fixtures",
-  "7": "Metric Injection Tokens",
-  "8": "Baggage Decorator",
-  "9": "CurrentSpan Decorator"
-}

package/graphify-out/.graphify_python

@@ -1 +0,0 @@
-/Users/pragmaticivan/.local/share/mise/installs/python/3.14.6/bin/python3.14

package/graphify-out/.graphify_root

@@ -1 +0,0 @@
-/Users/pragmaticivan/Code/pragmaticivan/nestjs-otel

package/graphify-out/GRAPH_REPORT.md

@@ -1,89 +0,0 @@
-# Graph Report - .  (2026-06-15)
-
-## Corpus Check
-- Corpus is ~6,192 words - fits in a single context window. You may not need a graph.
-
-## Summary
-- 157 nodes · 286 edges · 10 communities (6 shown, 4 thin omitted)
-- Extraction: 100% EXTRACTED · 0% INFERRED · 0% AMBIGUOUS
-- Token cost: 0 input · 0 output
-
-## Community Hubs (Navigation)
-- [[_COMMUNITY_Metric Decorators & Data|Metric Decorators & Data]]
-- [[_COMMUNITY_Span Decorator & Tests|Span Decorator & Tests]]
-- [[_COMMUNITY_Module Bootstrap & Tracing|Module Bootstrap & Tracing]]
-- [[_COMMUNITY_Wide Events|Wide Events]]
-- [[_COMMUNITY_Traceable Decorator|Traceable Decorator]]
-- [[_COMMUNITY_Counter Decorators & Metadata Utils|Counter Decorators & Metadata Utils]]
-- [[_COMMUNITY_Test Service Fixtures|Test Service Fixtures]]
-- [[_COMMUNITY_Metric Injection Tokens|Metric Injection Tokens]]
-- [[_COMMUNITY_Baggage Decorator|Baggage Decorator]]
-- [[_COMMUNITY_CurrentSpan Decorator|CurrentSpan Decorator]]
-
-## God Nodes (most connected - your core abstractions)
-1. `TestSpan` - 17 edges
-2. `OtelMetricOptions` - 12 edges
-3. `OpenTelemetryModuleOptions` - 9 edges
-4. `MetricService` - 9 edges
-5. `getOrCreate()` - 8 edges
-6. `OpenTelemetryCoreModule` - 8 edges
-7. `WideEventService` - 8 edges
-8. `OpenTelemetryModuleAsyncOptions` - 7 edges
-9. `TestService` - 7 edges
-10. `getWideEventBag()` - 7 edges
-
-## Surprising Connections (you probably didn't know these)
-- `InjectMetric()` --calls--> `getToken()`  [EXTRACTED]
-  src/metrics/injector.ts → src/metrics/utils.ts
-- `record()` --calls--> `getWideEventBag()`  [EXTRACTED]
-  src/wide-events/wide-event-field.decorator.ts → src/wide-events/wide-event.context.ts
-
-## Import Cycles
-- None detected.
-
-## Communities (10 total, 4 thin omitted)
-
-### Community 0 - "Metric Decorators & Data"
-Cohesion: 0.14
-Nodes (21): MetricParamDecorator, OtelCounter, OtelGauge, OtelHistogram, OtelObservableCounter, OtelObservableGauge, OtelObservableUpDownCounter, OtelUpDownCounter (+13 more)
-
-### Community 1 - "Span Decorator & Tests"
-Cohesion: 0.08
-Nodes (10): ExtendedSpanOptions, handleOnResult(), recordException(), Span(), SpanDecoratorOptions, LazyThenable, makeFailingLazyThenable(), makeLazyThenable() (+2 more)
-
-### Community 2 - "Module Bootstrap & Tracing"
-Cohesion: 0.15
-Nodes (8): OpenTelemetryMetrics, OpenTelemetryModuleAsyncOptions, OpenTelemetryModuleOptions, OpenTelemetryOptionsFactory, OpenTelemetryWideEvents, OpenTelemetryCoreModule, OpenTelemetryModule, TraceService
-
-### Community 3 - "Wide Events"
-Cohesion: 0.13
-Nodes (10): getWideEventBag(), WIDE_EVENT_CONTEXT_KEY, WideEventBag, isAttributeValue(), record(), WideEventField(), CatsController, executionContext (+2 more)
-
-### Community 4 - "Traceable Decorator"
-Cohesion: 0.22
-Nodes (3): TestTraceable, TestTraceableWithOptions, Traceable()
-
-### Community 5 - "Counter Decorators & Metadata Utils"
-Cohesion: 0.27
-Nodes (4): OtelInstanceCounter(), OtelMethodCounter(), TestClass, copyMetadataFromFunctionToFunction()
-
-## Knowledge Gaps
-- **20 isolated node(s):** `OpenTelemetryMetrics`, `OpenTelemetryWideEvents`, `MetricParamDecorator`, `OtelCounter`, `OtelUpDownCounter` (+15 more)
-  These have ≤1 connection - possible missing edges or undocumented components.
-- **4 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
-
-## Suggested Questions
-_Questions this graph is uniquely positioned to answer:_
-
-- **Why does `TestService` connect `Test Service Fixtures` to `Wide Events`?**
-  _High betweenness centrality (0.076) - this node is a cross-community bridge._
-- **What connects `OpenTelemetryMetrics`, `OpenTelemetryWideEvents`, `MetricParamDecorator` to the rest of the system?**
-  _20 weakly-connected nodes found - possible documentation gaps or missing edges._
-- **Should `Metric Decorators & Data` be split into smaller, more focused modules?**
-  _Cohesion score 0.13636363636363635 - nodes in this community are weakly interconnected._
-- **Should `Span Decorator & Tests` be split into smaller, more focused modules?**
-  _Cohesion score 0.08374384236453201 - nodes in this community are weakly interconnected._
-- **Should `Module Bootstrap & Tracing` be split into smaller, more focused modules?**
-  _Cohesion score 0.14814814814814814 - nodes in this community are weakly interconnected._
-- **Should `Wide Events` be split into smaller, more focused modules?**
-  _Cohesion score 0.1282051282051282 - nodes in this community are weakly interconnected._

package/graphify-out/cost.json

@@ -1,12 +0,0 @@
-{
-  "runs": [
-    {
-      "date": "2026-06-16T02:18:50.326220+00:00",
-      "input_tokens": 0,
-      "output_tokens": 0,
-      "files": 33
-    }
-  ],
-  "total_input_tokens": 0,
-  "total_output_tokens": 0
-}