@comprehend/telemetry-node

OpenTelemetry integration for comprehend.dev - automatically capture and analyze your Node.js application's architecture and performance.

Installation

npm install @comprehend/telemetry-node

Quick Start

Starting from scratch

If you don't have OpenTelemetry set up yet, here's a complete setup:

npm install @comprehend/telemetry-node @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { Resource } from '@opentelemetry/resources';
import { ComprehendDevSpanProcessor } from '@comprehend/telemetry-node';

// Set up OpenTelemetry with your service information
const sdk = new NodeSDK({
    resource: new Resource({
        'service.name': 'my-node-service',
        'service.namespace': 'production',
        'deployment.environment': 'prod'
    }),
    spanProcessors: [
        new ComprehendDevSpanProcessor({
            organization: 'your-org',  // Use your organization name
            token: process.env.COMPREHEND_INGESTION_TOKEN!,
            debug: true  // Optional: enable debug logging (or pass a custom logger function)
        })
    ],
    instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

// Graceful shutdown
process.on('SIGTERM', () => {
    sdk.shutdown().then(() => console.log('Tracing terminated'));
});

Adding to existing OpenTelemetry setup

If you already have OpenTelemetry configured, simply add the ComprehendDevSpanProcessor to your existing span processors:

import { ComprehendDevSpanProcessor } from '@comprehend/telemetry-node';

// Add to your existing span processors array
const comprehendProcessor = new ComprehendDevSpanProcessor({
    organization: 'your-org',
    token: process.env.COMPREHEND_INGESTION_TOKEN!,
    debug: false  // Optional
});

// If using NodeSDK:
const sdk = new NodeSDK({
    // ... your existing config
    spanProcessors: [
        // ... your existing processors
        comprehendProcessor
    ],
});

// Or if using TracerProvider directly:
tracerProvider.addSpanProcessor(comprehendProcessor);

Configuration

Set your comprehend.dev ingestion token as an environment variable:

export COMPREHEND_INGESTION_TOKEN=your-ingestion-token-here

Note: In production environments, the token should be stored in a secure secret management system (such as AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, Kubernetes Secrets, or your cloud provider's secret management service) and injected into the environment through your container orchestrator's workload definition or service configuration.

What it captures

This integration automatically captures:

• HTTP Routes - API endpoints and their usage patterns
• Database Operations - SQL queries with table operations analysis
• Service Dependencies - HTTP client calls to external services
• Performance Metrics - Request durations, response codes, error rates
• Service Architecture - Automatically maps your service relationships

Requirements

• Node.js 14+
• OpenTelemetry SDK (peer dependency)

Framework Support

Works with any Node.js framework that supports OpenTelemetry auto-instrumentation:

• Express
• Fastify
• Koa
• NestJS
• PostgreSQL
• MySQL
• MongoDB
• Prisma
• Sequelize
• TypeORM
• And more...

Learn More

• Visit comprehend.dev for documentation and to get your ingestion token
• OpenTelemetry JavaScript Documentation

Development

See DEVELOPMENT.md for development setup and release instructions.