otel-doctor

Diagnostic tool for OpenTelemetry SDK setup in Node.js

Quickly diagnose common OpenTelemetry configuration issues and get actionable recommendations.

Install

npm install -g @abhee11/otel-doctor

Or use with npx (no installation required):

npx @abhee11/otel-doctor

Usage

Run in your Node.js project directory:

otel-doctor

Example output:

🔍 OpenTelemetry SDK Diagnostic Report

✓ @opentelemetry/api installed (^1.7.0)
✓ @opentelemetry/sdk-node installed (^0.45.0)
✓ TracerProvider registered globally
✓ Instrumentations detected: @opentelemetry/instrumentation-http, @opentelemetry/instrumentation-express
⚠ No exporter configured - traces will be dropped!
  → Install an exporter: npm install @opentelemetry/exporter-trace-otlp-http
⚠ Collector unreachable at http://localhost:4318
  → Check if collector is running: docker ps | grep otel
ℹ Environment variables set: OTEL_SERVICE_NAME
ℹ Optional environment variables not set: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_TRACES_EXPORTER

📊 Summary:
  4 passed
  2 warnings
  1 info

⚠️  Warnings found. Your setup may be incomplete.

What It Checks

✅ Package Installation & Version Compatibility

• Verifies @opentelemetry/api is installed
• Checks for OpenTelemetry SDK packages
• NEW: Validates version compatibility matrix
• NEW: Detects known incompatible version combinations
• NEW: Warns about deprecated packages

✅ ESM vs CommonJS Detection

• NEW: Detects module type from package.json
• NEW: Validates correct loading method (--require vs --import)
• NEW: Warns if using wrong loader for module type

✅ Async Context Manager

• NEW: Checks for @opentelemetry/context-async-hooks
• NEW: Validates AsyncLocalStorageContextManager configuration
• NEW: Detects missing context propagation setup

✅ SDK Registration

• Confirms TracerProvider is registered globally
• Detects if using NoopTracerProvider (no-op mode)

✅ Instrumentations

• Scans for installed instrumentation packages
• Lists detected instrumentations (http, express, etc.)

✅ Exporters

• Checks if any exporter is configured
• Warns if traces will be dropped

✅ Environment Variables

• Reports on important OTEL environment variables
• Shows which variables are set/missing
• NEW: Vendor-specific environment variable validation

✅ Collector Connectivity

• Tests connection to OTLP collector endpoint
• Validates collector is reachable

✅ Sampling Configuration

• NEW: Detects sampling strategy
• NEW: Warns about AlwaysOnSampler in production
• NEW: Suggests optimal sampling rates

✅ Resource Detection

• NEW: Checks for cloud resource detectors
• NEW: Recommends detectors for your environment

Why Use otel-doctor?

Common problems it catches:

• ❌ "My traces aren't showing up" → No exporter configured
• ❌ "Context is lost in async operations" → Missing context manager
• ❌ "Collector connection refused" → Collector not running
• ❌ "No spans being created" → TracerProvider not registered

Saves you hours of debugging!

CLI Options

otel-doctor                      # Run all checks
otel-doctor --json               # Output results in JSON format (CI-friendly)
otel-doctor --profile splunk     # Check Splunk-specific configuration
otel-doctor --profile datadog    # Check Datadog-specific configuration
otel-doctor --help               # Show help
otel-doctor --version            # Show version

Vendor Profiles

otel-doctor supports vendor-specific configuration validation:

# Splunk Observability Cloud
otel-doctor --profile splunk

# Datadog APM
otel-doctor --profile datadog

# New Relic
otel-doctor --profile newrelic

# Honeycomb
otel-doctor --profile honeycomb

# Jaeger (local)
otel-doctor --profile jaeger

Each profile checks:

• Required environment variables
• Recommended packages
• Correct exporter endpoints
• Vendor-specific best practices

Requirements

• Node.js >= 14.0.0
• Run in a directory with package.json

Exit Codes

• 0 - All checks passed or only warnings
• 1 - Critical errors found

Use in CI/CD

Add to your CI pipeline to validate OpenTelemetry setup:

# .github/workflows/test.yml
- name: Validate OpenTelemetry setup
  run: npx otel-doctor

Roadmap

• [ ] Check for async_hooks context manager
• [ ] Validate sampler configuration
• [ ] Detect common misconfiguration patterns
• [ ] Support for custom check plugins
• [ ] JSON output format for CI integration

Contributing

Issues and PRs welcome!

License

MIT