@comprehend/telemetry-node

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

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/sdk-metrics @opentelemetry/auto-instrumentations-node

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

const comprehend = new ComprehendSDK({
    organization: 'your-org',
    token: process.env.COMPREHEND_SDK_TOKEN!,
    debug: true  // Optional: enable debug logging (or pass a custom logger function)
});

const sdk = new NodeSDK({
    resource: new Resource({
        'service.name': 'my-node-service',
        'service.namespace': 'production',
        'deployment.environment': 'prod'
    }),
    spanProcessors: [comprehend.getSpanProcessor()],
    metricReader: new PeriodicExportingMetricReader({
        exporter: comprehend.getMetricsExporter(),
        exportIntervalMillis: 15000
    }),
    instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

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

Adding to existing OpenTelemetry setup

If you already have OpenTelemetry configured, create a ComprehendSDK instance and add its processor and exporter:

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

const comprehend = new ComprehendSDK({
    organization: 'your-org',
    token: process.env.COMPREHEND_SDK_TOKEN!,
});

// Add to your NodeSDK config:
const sdk = new NodeSDK({
    // ... your existing config
    spanProcessors: [
        // ... your existing processors
        comprehend.getSpanProcessor()
    ],
    metricReader: new PeriodicExportingMetricReader({
        exporter: comprehend.getMetricsExporter(),
        exportIntervalMillis: 15000
    }),
});

Process and runtime metrics

For process-level and V8 runtime metrics (memory usage, event loop delay, GC duration, etc.), include @opentelemetry/instrumentation-runtime-node in your instrumentations:

npm install @opentelemetry/instrumentation-runtime-node

import { RuntimeNodeInstrumentation } from '@opentelemetry/instrumentation-runtime-node';

const sdk = new NodeSDK({
    // ...
    instrumentations: [
        getNodeAutoInstrumentations(),
        new RuntimeNodeInstrumentation(),
    ],
});

Host metrics (CPU and memory)

For process-level CPU utilization and memory usage, add @opentelemetry/host-metrics:

npm install @opentelemetry/host-metrics

import { HostMetrics } from '@opentelemetry/host-metrics';

// Start after sdk.start()
const hostMetrics = new HostMetrics({
    metricGroups: ['process.cpu', 'process.memory'],
});
hostMetrics.start();

This collects process.cpu.time, process.cpu.utilization, and process.memory.usage. The metricGroups option limits collection to process-level metrics only, avoiding the overhead of system-wide CPU, memory, and network data gathering.

Service instance identity

Include serviceInstanceIdDetector in your resourceDetectors to give each running process a unique identity that changes on every restart. This lets comprehend.dev distinguish between different instances of the same service and track restarts over time:

import { envDetector, hostDetector, processDetector, serviceInstanceIdDetector } from '@opentelemetry/resources';

const sdk = new NodeSDK({
    // ...
    resourceDetectors: [envDetector, processDetector, hostDetector, serviceInstanceIdDetector],
});

serviceInstanceIdDetector generates a random UUID (service.instance.id) at process startup. Note that specifying resourceDetectors explicitly replaces the NodeSDK defaults, so include the built-in detectors (envDetector, processDetector, hostDetector) alongside it.

Kubernetes / container resources

When running in containers or Kubernetes, add containerDetector to your resourceDetectors:

npm install @opentelemetry/resource-detector-container

import { envDetector, hostDetector, processDetector, serviceInstanceIdDetector } from '@opentelemetry/resources';
import { containerDetector } from '@opentelemetry/resource-detector-container';

const sdk = new NodeSDK({
    // ...
    resourceDetectors: [envDetector, processDetector, hostDetector, containerDetector, serviceInstanceIdDetector],
});

containerDetector reads container.id from /proc/self/cgroup. This works reliably with Docker-based runtimes but not on modern containerd-based Kubernetes clusters (which is the default since k8s 1.24), where the cgroup format does not expose the container ID in the expected location. Add it anyway — it will populate container.id when available and is a no-op otherwise.

For k8s identity attributes that cannot be read from the host (pod name, namespace, node), use the Kubernetes Downward API to inject them as OTEL_RESOURCE_ATTRIBUTES:

env:
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: k8s.pod.name=$(POD_NAME),k8s.namespace.name=$(POD_NAMESPACE),k8s.node.name=$(NODE_NAME)
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: POD_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace
  - name: NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName

Configuration

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

export COMPREHEND_SDK_TOKEN=your-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 (analysis done server-side)
• Service Dependencies - HTTP client calls to external services
• Performance Metrics - Request durations, response codes, error rates
• Service Architecture - Automatically maps your service relationships
• Trace Spans - Span identity and parent relationships for connecting observations to traces
• Runtime Metrics - Node.js memory, event loop, and V8 metrics
• Custom Metrics - Server-configured custom metric and span collection

Requirements

• Node.js 14+
• OpenTelemetry SDK (peer dependencies: @opentelemetry/api, @opentelemetry/sdk-trace-base, @opentelemetry/sdk-metrics)

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.