@eqxjs/nest-opentelemetry

Version: 3.2.1 (stable)

OpenTelemetry auto-instrumentation for NestJS applications. Wraps @opentelemetry/sdk-node with a pre-configured set of instrumentations, exporters, and resource detectors — all driven by environment variables.

Features

• Zero-code instrumentation — register once and all supported libraries are auto-instrumented
• Multiple exporters — OTLP (traces, metrics, logs) and Azure Monitor Application Insights
• Custom Kafka span enrichment — supports KafkaJS, eqxjs-kafkajs, and Confluent Kafka with M1/M2/M3 message protocol parsing
• Custom Socket.IO span enrichment — captures socket ID, key, and M1 protocol attributes
• Cloud resource detection — automatic detection for AWS, Azure, GCP, Alibaba, container, and more
• Graceful shutdown — listens for SIGTERM and beforeExit and flushes telemetry before exit

Installation

npm install @eqxjs/nest-opentelemetry

Usage

Register the SDK before your application loads by passing --require to Node.js:

node --require ./node_modules/@eqxjs/nest-opentelemetry/dist/register.js dist/main.js

Or in your package.json start script:

{
  "scripts": {
    "start": "node --require ./node_modules/@eqxjs/nest-opentelemetry/dist/register.js dist/main.js"
  }
}

Programmatic Usage

You can also import individual helpers from the package:

import {
  getNodeAutoInstrumentations,
  getResourceDetectors,
  InstrumentationConfigMap,
} from '@eqxjs/nest-opentelemetry';

Use getNodeAutoInstrumentations(config?) to build the instrumentation list with your own NodeSDK setup, and getResourceDetectors() to apply the environment-driven resource detector list.

Environment Variables

Exporters

| Variable | Description | |---|---| | TRACES_URL | OTLP endpoint for traces (default: http://localhost:4318/v1/traces) | | METRICS_URL | OTLP endpoint for metrics (default: http://localhost:4318/v1/metrics) | | LOGGER_URL | OTLP endpoint for logs (default: http://localhost:4318/v1/logs) | | APPLICATIONINSIGHTS_CONNECTION_STRING_TRACE | Azure Monitor connection string for traces (takes priority over TRACES_URL) | | APPLICATIONINSIGHTS_CONNECTION_STRING_METRIC | Azure Monitor connection string for metrics (takes priority over METRICS_URL) | | APPLICATIONINSIGHTS_CONNECTION_STRING_LOG | Azure Monitor connection string for logs (takes priority over LOGGER_URL) | | METRIC_EXPORT_INTERVAL | Metrics export interval in milliseconds (default: 60000) | | METRIC_PROMETHEUS_PORT | Expose a Prometheus scrape endpoint on this port (e.g. 8081). Takes effect only when neither APPLICATIONINSIGHTS_CONNECTION_STRING_METRIC nor METRICS_URL is set. |

Instrumentation

| Variable | Description | |---|---| | OTEL_HTTP_HEADER | Comma-separated list of HTTP header names to capture as span attributes on both request and response | | OTEL_NODE_ENABLED_INSTRUMENTATIONS | Comma-separated list of instrumentation suffixes to enable. When unset, all instrumentations are enabled. Example: http,grpc,pg |

Valid values for OTEL_NODE_ENABLED_INSTRUMENTATIONS:

| Value | Library | |---|---| | amqplib | AMQP (RabbitMQ) | | aws-lambda | AWS Lambda | | aws-sdk | AWS SDK | | bunyan | Bunyan logger | | cassandra-driver | Cassandra | | confluent-kafka | Confluent Kafka (node-rdkafka) | | confluent-kafka-js | Confluent Kafka (KafkaJS) | | connect | Connect | | cucumber | Cucumber | | dataloader | DataLoader | | dns | DNS | | eqxjs-ioredis | EqxJS IORedis | | eqxjs-kafkajs | EqxJS KafkaJS | | mongodb2 | MongoDB (legacy v2 driver) | | express | Express | | fastify | Fastify | | fs | File System (fs) | | generic-pool | Generic Pool | | graphql | GraphQL | | grpc | gRPC | | hapi | Hapi | | http | HTTP / HTTPS | | ioredis | IORedis | | kafkajs | KafkaJS | | knex | Knex | | koa | Koa | | lru-memoizer | LRU Memoizer | | memcached | Memcached | | mongodb | MongoDB | | mongodb2 | MongoDB (v2 driver) | | mongoose | Mongoose | | mysql | MySQL | | mysql2 | MySQL2 | | nestjs-core | NestJS core | | net | Net | | pg | PostgreSQL | | pino | Pino logger | | redis | Redis v2 | | redis-4 | Redis v4 | | restify | Restify | | router | Router | | socket.io | Socket.IO | | tedious | Tedious (MSSQL) | | winston | Winston logger |

Resource Detectors

| Variable | Description | |---|---| | OTEL_NODE_RESOURCE_DETECTORS | Comma-separated list of resource detectors. Defaults to all. Use none to disable all. |

Available detector values:

| Value | Detects | |---|---| | all | Enables every detector below | | none | Disables all detectors | | container | Container ID | | env | OTEL_RESOURCE_ATTRIBUTES environment variable | | host | Hostname | | os | OS name and version | | process | Process PID, runtime name, and version | | serviceinstance | Random service instance ID | | alibaba | Alibaba Cloud ECS metadata | | aws | AWS EC2 / ECS / EKS / Beanstalk / Lambda metadata | | azure | Azure App Service / Functions / VM metadata | | gcp | Google Cloud Platform metadata |

Deployment Attributes (applied to Kafka / Socket.IO spans)

| Variable | Span attribute set | |---|---| | CLOUD_ZONE | cloud.zone | | DEPLOYMENT_ENV | deployment.environment | | DEPLOYMENT_NAMESPACE | k8s.namespace.name |

Supported Instrumentations

| Library | Package | |---|---| | HTTP / HTTPS | @opentelemetry/instrumentation-http | | gRPC | @opentelemetry/instrumentation-grpc | | Express | @opentelemetry/instrumentation-express | | Fastify | @fastify/otel | | Koa | @opentelemetry/instrumentation-koa | | Hapi | @opentelemetry/instrumentation-hapi | | NestJS core | @opentelemetry/instrumentation-nestjs-core | | Socket.IO | @opentelemetry/instrumentation-socket.io | | GraphQL | @opentelemetry/instrumentation-graphql | | KafkaJS | opentelemetry-instrumentation-kafkajs | | EqxJS KafkaJS | opentelemetry-instrumentation-eqxjs-kafkajs | | Confluent Kafka (node-rdkafka) | opentelemetry-instrumentation-confluent-kafka | | Confluent Kafka (KafkaJS) | opentelemetry-instrumentation-confluent-kafka (KafkaJSInstrumentation) | | AMQP (RabbitMQ) | @opentelemetry/instrumentation-amqplib | | MongoDB | @opentelemetry/instrumentation-mongodb (enhanced reporting enabled) | | MongoDB v2 driver | opentelemetry-instrumentation-mongodb2 (enhanced reporting enabled) | | Mongoose | @opentelemetry/instrumentation-mongoose | | PostgreSQL | @opentelemetry/instrumentation-pg | | MySQL / MySQL2 | @opentelemetry/instrumentation-mysql, @opentelemetry/instrumentation-mysql2 | | Redis v2 / v4 | @opentelemetry/instrumentation-redis, @opentelemetry/instrumentation-redis-4 | | IORedis | @opentelemetry/instrumentation-ioredis, opentelemetry-instrumentation-eqxjs-ioredis | | Cassandra | @opentelemetry/instrumentation-cassandra-driver | | Memcached | @opentelemetry/instrumentation-memcached | | Knex | @opentelemetry/instrumentation-knex | | AWS SDK | @opentelemetry/instrumentation-aws-sdk | | AWS Lambda | @opentelemetry/instrumentation-aws-lambda | | DNS | @opentelemetry/instrumentation-dns | | Net | @opentelemetry/instrumentation-net | | FS | @opentelemetry/instrumentation-fs | | Pino | @opentelemetry/instrumentation-pino | | Winston | @opentelemetry/instrumentation-winston | | Bunyan | @opentelemetry/instrumentation-bunyan | | DataLoader | @opentelemetry/instrumentation-dataloader | | Generic Pool | @opentelemetry/instrumentation-generic-pool | | LRU Memoizer | @opentelemetry/instrumentation-lru-memoizer | | Connect | @opentelemetry/instrumentation-connect | | Restify | @opentelemetry/instrumentation-restify | | Router | @opentelemetry/instrumentation-router | | Tedious (MSSQL) | @opentelemetry/instrumentation-tedious | | Cucumber | @opentelemetry/instrumentation-cucumber |

Message Protocol Span Enrichment

Kafka producer/consumer hooks and Socket.IO hooks parse message payloads and add structured span attributes based on the detected message format.

M1 Protocol

Messages with a protocol field are parsed as M1 and produce the following attributes in addition to all M2 attributes:

| Attribute | Source field | |---|---| | M1.protocol.version | protocol.version | | M1.protocol.command | protocol.command | | M1.protocol.sub_command | protocol.subCommand | | M1.protocol.invoke | protocol.invoke | | M1.protocol.topic | protocol.topic |

M2 Protocol

Messages with a header field are parsed as M2:

| Attribute | Source field | |---|---| | enduser.id | header.identity.user | | M2.header.version | header.version | | M2.header.org_service | header.orgService | | M2.header.from | header.from | | M2.header.channel | header.channel | | M2.header.broker | header.broker | | M2.header.agent | header.agent | | M2.header.useCase | header.useCase | | M2.header.use_case_step | header.useCaseStep | | M2.header.use_case_age | header.useCaseAge | | M2.header.function_name | header.functionName | | M2.header.session | header.session | | M2.header.transaction | header.transaction |

M3 Protocol

Messages with a service field are parsed as M3:

| Attribute | Source field | |---|---| | enduser.id | service.identity.user | | M3.service.version | service.version | | M3.service.org_service | service.orgService | | M3.service.from | service.from | | M3.service.channel | service.channel | | M3.service.broker | service.broker | | M3.service.agent | service.agent | | M3.service.useCase | service.useCase | | M3.service.use_case_step | service.useCaseStep | | M3.service.use_case_age | service.useCaseAge | | M3.service.function_name | service.functionName | | M3.service.session | service.session | | M3.service.transaction | service.transaction |

Kafka Span Attributes

All Kafka spans (producer and consumer) include:

| Attribute | Description | |---|---| | kafka.direction | produce or consume | | kafka.topic | Topic name | | kafka.key | Message key | | kafka.partition | Message partition | | kafka.offset | Message offset | | kafka.header.<name> | Each message header value |

Build

npm run build

Output is emitted to ./dist.

License

ISC