This module provides an opinionated, plug-and-play wrapper around the OpenTelemetry Node SDK, specifically tailored for NestJS applications. It comes pre-configured with useful instrumentations like HTTP, Express, NestJS, TypeORM, and PostgreSQL.

📦 Installation

npm install @zzazz/otel

Or with yarn:

yarn add @zzazz/otel

Or with pnpm:

pnpm add @zzazz/otel

⚡ Quick Start

Import and initialize initOtel early in your app (before anything else)

// src/main.ts
import { initOtel } from '@zzazz/otel';

await initOtel({
  enabled: true,
  serviceName: 'my-nest-api',
  serviceVersion: '1.0.0',
  environment: 'production',
  endpoint: 'http://localhost:4318', // OTLP HTTP endpoint (collector)
  developerMode: false // keep it true for local development.
});

Then continue with your normal NestJS app bootstrap:

const app = await NestFactory.create(AppModule);
await app.listen(process.env.PORT || 3000);

⚙️ Configuration Options

| Option | Type | Default | Description | |---------------------|----------------------|---------------|-----------------------------------------------------------------------------| | enabled | boolean | true | Master toggle for enabling tracing | | serviceName | string | required | Your service name used in trace metadata | | serviceVersion | string | '1.0.0' | Optional version of your service | | environment | string | 'local' | Useful for tagging traces from different environments | | endpoint | string | required | OTLP HTTP collector endpoint (e.g., http://localhost:4318) | | developerMode | boolean | false | If true, uses ConsoleSpanExporter instead of OTLP (for local debugging) | | instrumentations | Instrumentation[] | Built-in set | Override or extend default instrumentations |

🧩 Built-in Instrumentations

By default, this SDK includes the following instrumentations:

• @opentelemetry/instrumentation-http
• @opentelemetry/instrumentation-express
• @opentelemetry/instrumentation-nestjs-core
• @opentelemetry/instrumentation-typeorm
• @opentelemetry/instrumentation-pg

You can override them by passing a custom instrumentations array.

🧪 Developer Mode

Use developerMode: true to log all spans to the console (useful for local development without setting up a collector).

🔍 OTLP Collector Setup (Optional)

To collect traces locally, you can run an OpenTelemetry Collector:

docker run -p 4318:4318 otel/opentelemetry-collector-contrib:latest

Make sure the endpoint in your config points to this URL:

endpoint: 'http://localhost:4318'

🛑 Graceful Shutdown

The SDK listens for SIGINT, SIGTERM, and uncaughtException and automatically shuts down OpenTelemetry SDK and flushes spans.

Make sure the endpoint in your config points to this URL:

endpoint: 'http://localhost:4318'

📄 License

MIT