![\"NestJS](\"https://nestjs.com/img/logo-small.svg\"){kind=logo}
\n\n \n
Auto-instrumented observability for NestJS applications — traces, errors, logs, jobs and profiles, with no manual span wiring.
\n\n\n![\"NPM](\"https://img.shields.io/npm/v/@nestjs/observe.svg\")
\n![\"NPM](\"https://img.shields.io/npm/dm/@nestjs/observe.svg\")
\n![\"Package](\"https://img.shields.io/npm/l/@nestjs/observe.svg\")
\n
\n Live demo ·\n Website ·\n Documentation\n
\n\n## What it is\n\n`@nestjs/observe` instruments a NestJS application from the inside. It hooks\ninto Nest's own request lifecycle — controllers, interceptors, guards, queue\nconsumers, resolvers — rather than wrapping a generic Node.js agent around the\nframework, so a trace is named in the vocabulary you wrote the code in: classes\nand methods, not just HTTP routes.\n\nInstall it, set two environment variables, and the application starts reporting:\n\n- **Requests, jobs and RPC calls** — HTTP, GraphQL, microservices (RPC/gRPC),\n BullMQ consumers and `@nestjs/schedule` cron, interval and timeout jobs.\n- **Distributed traces** with per-span self time, correlated across services.\n- **Errors**, grouped by fingerprint, with the source frame and the trace that\n produced them.\n- **Logs**, correlated to the request that wrote them.\n- **Runtime and custom metrics**, plus on-demand **CPU profiles**.\n\nTelemetry is serialised on a detached worker thread and shipped from there, so\nthe request path is untouched by the reporting.\n\n### Why not just OpenTelemetry?\n\nOpenTelemetry is the right answer when you need vendor neutrality across a\npolyglot estate, and this agent is not a replacement for it. It is a different\ntrade: no collector to run, no exporter pipeline to configure, no manual\ninstrumentation for the framework's own lifecycle — and spans named after your\nNest classes and methods, which generic Node.js instrumentation cannot produce\nbecause it cannot see them. If you would otherwise spend a week wiring a\ncollector and still not know which provider spent the time, this is the\nshortcut.\n\n## Seeing it before installing\n\n**[observe-demo.nestjs.com](https://www.observe-demo.nestjs.com/dashboard)** is the whole\ndashboard running over a generated dataset from a busy service — real request\nvolumes, traces with waterfalls, errors, jobs and alerts. No signup, nothing to\ninstall.\n\n```bash\n$ npm install @nestjs/observe\n```\n\n## Getting credentials\n\nSign up at **[observe.nestjs.com](https://observe.nestjs.com)** and create a\nservice. The dashboard issues an **app key** and an **app secret**, which the\nagent sends on every ingest request.\n\n**Free for up to 300,000 events a month**, which covers most individual projects, startups, and small applications.\n\nThe secret is shown once and is not retrievable afterwards - store it with the\nrest of your secrets and supply both from the environment:\n\n```bash\nOBSERVE_APP_KEY=...\nOBSERVE_APP_SECRET=...\n```\n\nWithout valid credentials the collector answers `401` and telemetry is dropped.\n\n## Quick start\n\n`createObserveModule()` returns both the dynamic module and the instrumentation\nhook Nest needs at bootstrap:\n\n```ts\n// observe.ts\nimport { createObserveModule } from \"@nestjs/observe\";\n\nexport const { ObserveModule, ObserveInstrument } = createObserveModule();\n```\n\n```ts\n// app.module.ts\nimport { Module } from \"@nestjs/common\";\nimport { ObserveModule } from \"./observe\";\n\n@Module({\n imports: [\n ObserveModule.forRoot({\n appKey: process.env.OBSERVE_APP_KEY!,\n appSecret: process.env.OBSERVE_APP_SECRET!,\n serviceId: \"my-service\",\n }),\n ],\n})\nexport class AppModule {}\n```\n\n```ts\n// main.ts\nimport { NestFactory } from \"@nestjs/core\";\nimport { AppModule } from \"./app.module\";\nimport { ObserveInstrument } from \"./observe\";\n\nasync function bootstrap() {\n const app = await NestFactory.create(AppModule, {\n instrument: ObserveInstrument,\n });\n await app.listen(3000);\n}\nbootstrap();\n```\n\n### Async configuration\n\n`ObserveModule.forRootAsync()` resolves the options from the DI container, via\n`useFactory`, `useClass`, or `useExisting`:\n\n```ts\nObserveModule.forRootAsync({\n imports: [ConfigModule],\n inject: [ConfigService],\n useFactory: (config: ConfigService) => ({\n appKey: config.getOrThrow(\"OBSERVE_APP_KEY\"),\n appSecret: config.getOrThrow(\"OBSERVE_APP_SECRET\"),\n serviceId: config.getOrThrow(\"OBSERVE_SERVICE_ID\"),\n }),\n});\n```\n\n`useClass` and `useExisting` take a class implementing `ObserveOptionsFactory`:\n\n```ts\n@Injectable()\nexport class ObserveConfig implements ObserveOptionsFactory {\n createObserveOptions(): ObserveOptions {\n return { appKey: \"...\", appSecret: \"...\", serviceId: \"...\" };\n }\n}\n```\n\n## Repeated spans\n\nEvery provider is instrumented by default, framework-owned ones included, and\nsome of them run in loops the application never wrote. A `ValidationPipe`\nregistered through `APP_PIPE` runs once per argument of every GraphQL field\nresolver, so a single list query produces hundreds or thousands of identical\nsibling spans under the operation - each of them a metered event, and together\nsaying nothing a count would not.\n\nThe agent collapses those before a trace leaves the process. When more than\n`threshold` siblings under one parent share a class and method:\n\n- the slowest `keepSlowest` of them stay as ordinary spans,\n- any instance that errored stays as an ordinary span, whatever its duration,\n- the rest are replaced by one node that carries how many calls it stands for\n and the **sum** of their durations.\n\nNothing is skipped outright and no duration cut-off is involved: what\nvalidation costs is specific to each application, and the calls that explain a\nslow request are exactly the ones kept whole. The collapsed node is metered as\na single event.\n\n```ts\nObserveModule.forRoot({\n // ...\n spanCollapse: { threshold: 20, keepSlowest: 3 }, // the defaults\n // spanCollapse: false, // ship every span\n});\n```\n\nWhat a collapsed node means:\n\n- Its `observe.collapsed` tag is the number of calls it replaces, and its name\n reads `ValidationPipe.transform ×27` so a waterfall shows an aggregate rather\n than one more call.\n- `duration` is the sum of the replaced calls' durations, not the wall-clock\n span between the first and the last. That is what keeps the parent's self\n time - its duration minus its children's - exactly what it was.\n- `startOffset` is the earliest replaced call's, and the node sits where that\n call sat among its siblings. Ordering _among_ the replaced calls is lost,\n which is acceptable for calls that are identical by construction.\n- The replaced calls' own children are carried onto the node, so the time of\n whatever they called is still attributed to the class that spent it; a\n repeated frame beneath them collapses in turn.\n- Tags of the replaced calls are dropped. Manual spans are never collapsed.\n\nThe wire format is unchanged: the count travels inside `t` (tags), next to `n`\nname, `o` origin, `d` duration, `e` error, `c` className, `m` methodKey, `ch`\nchildren, `s` spanId and `so` startOffset. A collector that does not know the\ntag stores it like any other and attributes the node as one call of its class\nrather than as the number it carries.\n\n## What it records without any code\n\nOnce the module and the instrument are in place, the agent reports, with no further changes to your application:\n\n- **Requests, GraphQL operations, RPC messages, WebSocket gateway messages, queue jobs and scheduled jobs**, each with its tree of provider method calls.\n- **Database queries**, as a span under the method that ran them, for `pg`, `mysql2` and `mongodb`. Anything built on those drivers is covered without being known by name: TypeORM, Drizzle, MikroORM and Mongoose are tested in this repository, and others (Knex, Sequelize) go through the same driver calls. The statement is recorded with every value removed (`SELECT \"o\".\"id\" FROM \"orders\" \"o\" WHERE \"o\".\"customer_id\" = $1`). Prisma's Rust query engine does not go through these drivers and is not covered yet.\n- **Outbound HTTP calls** made with `fetch`/`undici` or `node:http`/`https` (so Axios too), as `POST api.stripe.com`. The current trace id is forwarded as `x-request-id`, so a service that also runs the agent continues the same trace; a header you set yourself is never overwritten.\n- **Trace ids across queues**: a BullMQ or Bull job enqueued while handling a request carries that request's trace id, so the request and its job show up as one trace. Repeatable (cron) jobs start their own.\n\nQuery and outbound-HTTP spans are not billed as events. Turn them off with `outgoing: false`, or one side with `outgoing: { database: false }` / `outgoing: { http: false }`.\n\n## Capturing failed and slow requests\n\nThe inputs behind a failing request are usually the fastest way to reproduce it. The agent keeps them only for the requests worth it - never for ordinary traffic:\n\n```ts\nObserveModule.forRoot({\n // ...\n http: {\n capture: {\n // Also capture requests that took at least this long, failed or not.\n slowerThanMs: 2000,\n // Off by default: a body is your users' data. Capped at 2 KB unless\n // you pass `{ maxBytes }` (at most 16 KB).\n body: true,\n // Defaults to a short list with nothing that authenticates or\n // identifies anyone: accept, content-type, user-agent, ...\n // Pass your own list, or `false` for none.\n headers: [\"content-type\", \"user-agent\", \"x-tenant-id\"],\n },\n },\n});\n```\n\nA failed request is always captured (headers only, unless `body` is on); `capture: false` turns the feature off. Everything captured goes through the same redaction as error messages and logs before it leaves the process - sensitive keys by name, secrets by pattern - so naming `authorization` in `headers` records `[REDACTED]`.\n\n## Optional peer dependencies\n\nProtocol integrations are only loaded when you use them, and their packages are optional peers:\n\n- `@nestjs/microservices` - RPC/microservice instrumentation\n- `@nestjs/graphql` - GraphQL operation instrumentation\n- `@nestjs/bullmq` and `bullmq` - queue/job instrumentation\n- `@nestjs/bull` and `bull` - the same, for legacy Bull\n- `@nestjs/websockets` - WebSocket gateway instrumentation (`ws` and socket.io adapters)\n- `@nestjs/schedule` - scheduled job (`@Cron`, `@Interval`, `@Timeout`) instrumentation\n\n## Test\n\n```bash\n# unit tests\n$ npm test\n\n# integration tests (boot real Nest apps on real ports)\n$ npm run test:int\n```\n\n## Module format\n\nThe package ships as ESM only. CommonJS consumers can still `require()` it\nthrough Node's `require(esm)` support, which is why the engine floor is\n**Node 20.19** (or 22.12) rather than 20.0 - and why nothing in the module graph\nuses top-level await, which `require(esm)` cannot load.\n\n```js\n// works from CommonJS on Node >= 20.19\nconst { createObserveModule } = require(\"@nestjs/observe\");\n```\n\n## Stay in touch\n\n- Dashboard — [observe.nestjs.com](https://observe.nestjs.com)\n- Live demo — [observe-demo.nestjs.com](https://www.observe-demo.nestjs.com/dashboard)\n- Documentation — [docs.nestjs.com](https://docs.nestjs.com)\n- Twitter — [@nestframework](https://twitter.com/nestframework)\n\n## License\n\n`@nestjs/observe` is [MIT licensed](LICENSE).\n","readmeFilename":"README.md"}