Dash0 OpenTelemetry

Side-effect auto-initialization package for Node.js OpenTelemetry instrumentation. No programmatic API - configures via environment variables only.

Package Information

• Package: @dash0/opentelemetry
• Type: npm
• Language: TypeScript
• Installation: npm install @dash0/opentelemetry
• Minimum Node.js: 14.0.0

Usage Pattern

Load via Node.js require flag or at application entry point:

node --require @dash0/opentelemetry app.js

require('@dash0/opentelemetry');
// Rest of application code

Automatically initializes OpenTelemetry SDK with OTLP exporters for traces, metrics, and logs.

Required Configuration

// DASH0_OTEL_COLLECTOR_BASE_URL (REQUIRED)
// Type: string (URL)
// Description: Base URL of OpenTelemetry collector
// Endpoints: ${url}/v1/traces, ${url}/v1/metrics, ${url}/v1/logs
// Example: "http://collector.example.com:4318"

Initialization fails without this variable set.

Environment Variables

Core Control

Service Identification

Service Name Precedence (highest to lowest):

1. OTEL_SERVICE_NAME
2. service.name in OTEL_RESOURCE_ATTRIBUTES
3. Auto-detection from package.json (if DASH0_AUTOMATIC_SERVICE_NAME != "false")

Lifecycle Management

Instrumentation Control

Available instrumentations: http, https, express, fastify, graphql, grpc, ioredis, kafkajs, mongodb, mysql, mysql2, nestjs-core, pg, redis, and more. See OpenTelemetry docs.

Example: OTEL_NODE_ENABLED_INSTRUMENTATIONS=http,express,pg

Resource Detection

Built-in detectors: env, process, container, host Dash0-specific (always added): podUid, serviceNameFallback

Metrics Configuration

Automatic Resource Attributes

Always added to all telemetry:

{
  'telemetry.distro.name': 'dash0-nodejs',
  'telemetry.distro.version': string, // From package.json
  'service.name': string,              // If auto-detection enabled
  'service.version': string,           // If auto-detection enabled
  'k8s.pod.uid': string,               // When running in Kubernetes
  // Standard OpenTelemetry attributes from resource detectors
}

Pod UID Detection: Reads from /proc/self/mountinfo (cgroup v1) or /proc/self/cgroup (cgroup v2) when /etc/hosts indicates Kubernetes environment.

SDK Version Selection

Automatically selects OpenTelemetry SDK based on Node.js version:

• SDK 1.x: Node.js 14.x-15.x, 16.x-18.18.x, 20.0.x-20.5.x
• SDK 2.x: Node.js >= 18.19.0, >= 20.6.0
• Supported: Node.js >= 14.0.0
• Warning logged: Node.js >= 25.0.0 (untested)

Export Configuration

Protocol: OTLP over HTTP with Protocol Buffers

Processors:

• Traces: BatchSpanProcessor
• Metrics: PeriodicExportingMetricReader
• Logs: BatchLogRecordProcessor

Endpoints:

• ${DASH0_OTEL_COLLECTOR_BASE_URL}/v1/traces
• ${DASH0_OTEL_COLLECTOR_BASE_URL}/v1/metrics
• ${DASH0_OTEL_COLLECTOR_BASE_URL}/v1/logs

Error Conditions

Initialization fails and logs to stderr:

1. DASH0_DISABLE=true → "Distribution has been disabled"
2. DASH0_OTEL_COLLECTOR_BASE_URL not set → "DASH0_OTEL_COLLECTOR_BASE_URL is not set"
3. Node.js < 14.0.0 → "Does not support this Node.js runtime version"
4. Initialization exception → "Initialization failed: ${error}"

Behavior on failure: Application continues normally, no telemetry collected.

Configuration Example

# Required
export DASH0_OTEL_COLLECTOR_BASE_URL=http://collector.example.com:4318

# Optional overrides
export OTEL_SERVICE_NAME=my-service
export OTEL_RESOURCE_ATTRIBUTES=environment=production,team=backend

# Selective instrumentation
export OTEL_NODE_ENABLED_INSTRUMENTATIONS=http,express,pg,redis

# Graceful shutdown
export DASH0_FLUSH_ON_EMPTY_EVENT_LOOP=true

# Start with instrumentation
node --require @dash0/opentelemetry app.js

Kubernetes Deployment

env:
- name: NODE_OPTIONS
  value: "--require @dash0/opentelemetry"
- name: DASH0_OTEL_COLLECTOR_BASE_URL
  value: "http://collector.dash0-system.svc.cluster.local:4318"