@interfere/nest

NestJS SDK for Interfere. Auto-captures uncaught exceptions and creates per-request spans for controllers, guards, pipes, interceptors, and middleware.

Install

npm install @interfere/nest
# or
bun add @interfere/nest
# or
pnpm add @interfere/nest

Setup

The SDK uses two subpath imports to avoid loading @nestjs/* before instrumentation hooks are registered:

• @interfere/nest/instrument — SDK init, error capture, span utilities (no @nestjs/* imports)
• @interfere/nest/module — InterfereModule and InterfereExceptionFilter (imports @nestjs/*)

1. Create instrument.ts

This file must be imported before any @nestjs/* module. It registers OTel instrumentation hooks that patch NestJS internals for automatic span creation.

// src/instrument.ts
import { init } from "@interfere/nest/instrument";

init({
  serviceName: "my-api",
  debug: true, // logs init status and exporter results to stdout
});

init() is synchronous and works in both ESM and CJS projects.

2. Import it first in main.ts

// src/main.ts
import "./instrument";

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

3. Register the module in app.module.ts

InterfereModule.forRoot() registers a global exception filter that captures 5xx errors and uncaught throws. 4xx responses (client errors) are not reported — they still produce OTel request spans but don't create error events.

// src/app.module.ts
import { Module } from "@nestjs/common";
import { InterfereModule } from "@interfere/nest/module";

@Module({ imports: [InterfereModule.forRoot()] })
export class AppModule {}

Build & Deploy

Install @interfere/cli as a dev dependency and add a postbuild script so source maps are uploaded and the release is registered with the collector. Without this step, the collector will reject spans from production deployments.

npm install -D @interfere/cli

{
  "scripts": {
    "build": "tsc",
    "postbuild": "interfere sourcemaps upload ./dist"
  }
}

The CLI derives the release slug from the same commit SHA the SDK uses at runtime (INTERFERE_SOURCE_ID, GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, or git rev-parse HEAD). Both must see the same SHA for the slugs to match. See the @interfere/cli README for full options, Docker examples, and CI setup.

Environment Variables

| Variable | Where | Purpose | |---|---|---| | INTERFERE_PUBLIC_KEY | Runtime | Routes spans to your surface (interfere_pub_us_* or interfere_pub_eu_*) | | INTERFERE_API_KEY | CI / Build | Authenticates source map uploads and release registration (interfere_secret_us_* or interfere_secret_eu_*) | | INTERFERE_SOURCE_ID | Both | Override the commit SHA used to derive the release slug. Falls back to GITHUB_SHA, VERCEL_GIT_COMMIT_SHA, or git rev-parse HEAD. | | INTERFERE_DEBUG | Runtime | Set to 1 to enable debug logging without changing code. Equivalent to debug: true in init(). |

What gets captured

| Signal | When | Subpath | |---|---|---| | Request spans (middleware, guards, pipes, interceptors) | Every HTTP request | @interfere/nest/instrument | | Error events (5xx, uncaught throws) | Exceptions that reach the global filter | @interfere/nest/module | | Manual spans (withSpan, captureError) | Anywhere in your code | @interfere/nest/instrument |

Compatibility

• NestJS 10.x and 11.x
• Node.js >= 18.19.0
• Works with Express (default) and Fastify adapters
• CJS and ESM projects