nestjs-otel 8.0.2 → 8.0.4-alpha.0

package/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "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

@@ -0,0 +1,14 @@
+{
+  "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)"
+    ]
+  }
+}

package/.tmp_build.out

@@ -0,0 +1,3 @@
+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/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`nestjs-otel` — NestJS module wrapping OpenTelemetry (`@opentelemetry/api`). Published library (`main: lib/index.js`). Provides tracing, metrics, and wide-events to NestJS apps. Node >= 22. NestJS 11 peer dep.
+
+The library does **not** start the OTEL SDK. Consumers create their own `NodeSDK` (`tracing.ts`) and call `otelSDK.start()` before `NestFactory.create`. This module reads the global tracer/meter providers the SDK registers (`trace.getTracer`, `metrics.getMeterProvider`).
+
+## Commands
+
+```bash
+npm run build         # tsc → lib/ (prebuild rimraf's lib first)
+npm run lint          # ultracite check (biome wrapper)
+npm run format        # ultracite fix (auto-fix lint)
+npm test              # unit + e2e
+npm run test:unit     # jest, *.spec.ts under src/
+npm run test:e2e      # jest tests/jest-e2e.json, --runInBand
+npm run test:coverage
+npm run test:watch
+```
+
+Run a single test: `npx jest src/wide-events/wide-event.service.spec.ts` (or `-t "<test name>"`). E2E single: `npx jest --config ./tests/jest-e2e.json tests/e2e/<file>.e2e-spec.ts`.
+
+Unit specs live next to source under `src/`. E2E specs in `tests/e2e/` run against `tests/fixture-app/` (a real NestJS app). Commits use Conventional Commits (commitlint + husky). `lint-staged` runs `ultracite fix` on staged files.
+
+## Architecture
+
+`OpenTelemetryModule.forRoot(options)` / `forRootAsync(options)` (`src/opentelemetry.module.ts`) are thin shells delegating to `OpenTelemetryCoreModule` (`src/opentelemetry-core.module.ts`). The core module is `@Global`, registers + exports `TraceService`, `MetricService`, `WideEventService`, `WideEventInterceptor`, and the `OPENTELEMETRY_MODULE_OPTIONS` token. `onApplicationBootstrap` is the only runtime side effect — it starts `HostMetrics` when `options.metrics.hostMetrics` is true. `forRootAsync` supports `useFactory` / `useClass` / `useExisting` via `OpenTelemetryOptionsFactory`.
+
+Three feature areas, each exported through `src/index.ts`:
+
+- **tracing** (`src/tracing/`): `TraceService` is a thin accessor over the global tracer. The real work is in decorators (`src/tracing/decorators/`): `@Span(name?, options?)` wraps a method in `startActiveSpan`, handles sync + Promise returns, records exceptions, supports an `onResult` callback to set attributes from the return value. `@Traceable` applies `@Span` to every method of a class. `@Baggage` / `@CurrentSpan` are param decorators. Decorators preserve the original function name/metadata via a `Proxy` + `copyMetadataFromFunctionToFunction` (`src/opentelemetry.utils.ts`) — critical so OpenAPI/Nest reflection still works.
+
+- **metrics** (`src/metrics/`): `MetricService` exposes `getCounter`/`getHistogram`/`getGauge`/observable variants, all delegating to `getOrCreate*` in `src/metrics/metric-data.ts`, which caches instruments by name in a module-level map (idempotent re-fetch). `@InjectMetric(name)` (`src/metrics/injector.ts`) injects a named instrument via a DI token from `getToken`. Class/method decorators in `src/metrics/decorators/` (`OtelInstanceCounter`, `OtelMethodCounter`, etc.) auto-instrument.
+
+- **wide-events** (`src/wide-events/`): one structured event (a wide span) per request. `WideEventInterceptor` opens a `WideEventBag` (a `Map`) stored on the active OTEL context under `WIDE_EVENT_CONTEXT_KEY`, then on `finalize` flushes all accumulated attributes onto the span that was active when the request entered. `WideEventService` (`set`/`setMany`/`increment`/`startTimer`) and the `@WideEventField` decorator mutate that bag via `getWideEventBag()` — all **no-ops outside an intercepted request**. The interceptor seeds `code.function.name` plus an optional `options.wideEvents.seed(executionContext)`, and records `error.type`/`error.message` on failure. Register globally with `APP_INTERCEPTOR` or per-controller with `@UseInterceptors`.
+
+Options/interfaces in `src/interfaces/`. Constants (token, tracer name `OTEL_TRACER_NAME`) in `src/opentelemetry.constants.ts`.
+
+## Conventions
+
+- Lint is `ultracite` (extends biome). Config in `biome.jsonc` already disables `noExplicitAny`, `useAwait`, barrel-file warnings — `any` is used freely in decorator code by design. Run `npm run format` before committing.
+- Public API symbols are tagged `@publicApi`; internal ones `@internal`. Keep new exports wired through `src/index.ts`.
+- Decorators must not break function identity — when adding/altering a method decorator, preserve name + metadata as the existing ones do.
+
+## graphify
+
+This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).

package/README.md

@@ -306,6 +306,125 @@ export class BookService {
 }
 ```
 
+## Wide Events
+
+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.
+
+1. Register the interceptor globally:
+
+```ts
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { OpenTelemetryModule, WideEventInterceptor } from 'nestjs-otel';
+
+@Module({
+  imports: [OpenTelemetryModule.forRoot()],
+  providers: [
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: WideEventInterceptor,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+The example above opens a wide event for **every** request in the application. To limit wide events to specific controllers instead, skip the `APP_INTERCEPTOR` provider and apply the interceptor directly with `@UseInterceptors`:
+
+```ts
+import { Controller, Get, UseInterceptors } from '@nestjs/common';
+import { WideEventInterceptor } from 'nestjs-otel';
+
+@Controller('checkout')
+@UseInterceptors(WideEventInterceptor)
+export class CheckoutController {
+  // every route in this controller now emits a wide event
+}
+```
+
+2. Enrich the event from anywhere in the request:
+
+```ts
+import { WideEventService } from 'nestjs-otel';
+
+@Injectable()
+export class CheckoutService {
+  constructor(private readonly wideEvent: WideEventService) {}
+
+  async checkout(cart: Cart) {
+    this.wideEvent.setMany({
+      'user.id': cart.userId,
+      'cart.items': cart.items.length,
+      'cart.total': cart.total,
+    });
+
+    const stopTimer = this.wideEvent.startTimer('payment.duration_ms');
+    await this.paymentGateway.charge(cart);
+    stopTimer();
+
+    this.wideEvent.increment('db.queries');
+  }
+}
+```
+
+All accumulated attributes land on the root span as a single wide event:
+
+```
+http_request
+├── code.function.name: CheckoutController.checkout
+├── user.id: u-123
+├── cart.items: 3
+├── cart.total: 42.5
+├── payment.duration_ms: 132.7
+├── db.queries: 1
+├── error.type: PaymentDeclinedError   (set automatically on errors)
+└── error.message: card declined       (set automatically on errors)
+```
+
+Notes:
+
+- The interceptor seeds `code.function.name` (`<Controller>.<handler>`) automatically and records `error.type`/`error.message` 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.
+
+### Seeding baseline attributes
+
+Use the `seed` option to populate baseline attributes on every request (e.g. ids derived from the authenticated request). It runs after guards, so `req.user` is available. A throwing seed never breaks the request — the error is recorded under `wide_event.seed.error`.
+
+```ts
+OpenTelemetryModule.forRoot({
+  wideEvents: {
+    seed: (ctx) => {
+      const req = ctx.switchToHttp().getRequest();
+      return {
+        'app.version': process.env.BUILD_SHA,
+        'user.id': req.user?.id,
+      };
+    },
+  },
+});
+```
+
+Static values (version, region, ...) are often better modeled as OpenTelemetry [Resource](https://opentelemetry.io/docs/specs/otel/resource/sdk/) attributes; reserve `seed` for per-request derivations.
+
+### `@WideEventField` decorator
+
+Capture a method's return value (resolved value for async methods) onto the current wide event without calling the service manually. Works on any provider method that runs within the request's async context. A failing projection or a non-attribute value is silently skipped.
+
+```ts
+import { WideEventField } from 'nestjs-otel';
+
+@Injectable()
+export class BooksService {
+  // records `books.count` = result.length
+  @WideEventField('books.count', (books: string[]) => books.length)
+  async getBooks() {
+    return ['Book 1', 'Book 2'];
+  }
+}
+```
+
 ## 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/graphify-out/.graphify_labels.json

@@ -0,0 +1,12 @@
+{
+  "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

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

package/graphify-out/.graphify_root

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

package/graphify-out/GRAPH_REPORT.md

@@ -0,0 +1,89 @@
+# 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

@@ -0,0 +1,12 @@
+{
+  "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
+}