@develop-x/nest-tracing

Overview

@develop-x/nest-tracing is a NestJS package that provides OpenTelemetry distributed tracing capabilities for your applications. It automatically instruments your Node.js application and exports trace data to OTLP-compatible backends.

Installation

npm install @develop-x/nest-tracing

Features

• Automatic Instrumentation: Automatically instruments popular Node.js libraries and frameworks
• OTLP Export: Exports traces to OpenTelemetry Protocol (OTLP) compatible backends
• Easy Configuration: Simple setup with minimal configuration required
• Environment Variable Support: Supports standard OpenTelemetry environment variables

Usage

Basic Setup

Initialize tracing at the very beginning of your application, before importing any other modules:

// main.ts or app.ts
import { initializeTracing } from '@develop-x/nest-tracing';

// Initialize tracing before any other imports
await initializeTracing({
  serviceName: 'my-service',
  otlpUrl: 'http://localhost:4318/v1/traces'
});

// Now import your application modules
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

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

Configuration Options

interface TracingOptions {
  serviceName: string;    // Name of your service
  otlpUrl?: string;      // OTLP endpoint URL (optional)
}

Environment Variables

The package supports standard OpenTelemetry environment variables:

• OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint URL
• SERVICE_NAME: Service name for tracing

Example with Environment Variables

// If environment variables are set, you can use minimal configuration
await initializeTracing({
  serviceName: process.env.SERVICE_NAME || 'my-service'
});

Supported Instrumentations

The package automatically instruments the following libraries:

• HTTP/HTTPS requests and responses
• Express.js applications
• Database drivers (MySQL, PostgreSQL, MongoDB, etc.)
• Redis clients
• And many more through @opentelemetry/auto-instrumentations-node

Integration with Observability Platforms

Jaeger

await initializeTracing({
  serviceName: 'my-service',
  otlpUrl: 'http://jaeger:14268/api/traces'
});

Zipkin

await initializeTracing({
  serviceName: 'my-service',
  otlpUrl: 'http://zipkin:9411/api/v2/spans'
});

OpenTelemetry Collector

await initializeTracing({
  serviceName: 'my-service',
  otlpUrl: 'http://otel-collector:4318/v1/traces'
});

Best Practices

1. Initialize Early: Always initialize tracing before importing any other modules
2. Service Naming: Use descriptive and consistent service names across your microservices
3. Environment Configuration: Use environment variables for different deployment environments
4. Error Handling: The package includes built-in error handling for initialization failures

Troubleshooting

Common Issues

1. Tracing not working: Ensure tracing is initialized before any other imports
2. No traces appearing: Check that the OTLP endpoint is accessible and correct
3. Performance impact: The auto-instrumentation has minimal performance overhead

Debug Mode

To enable debug logging, set the environment variable:

export OTEL_LOG_LEVEL=debug

Dependencies

• @opentelemetry/sdk-node: OpenTelemetry Node.js SDK
• @opentelemetry/auto-instrumentations-node: Automatic instrumentation
• @opentelemetry/exporter-trace-otlp-http: OTLP HTTP trace exporter

License

ISC

Support

For issues and questions, please refer to the project repository or contact the development team.