@eqxjs/nest-opentelemetry

中文文档

3.2.2发布于 2026/03/30ISCTypeScriptCommonJS近 30 天下载 1975

Opentelemetry Service for nestjs

此软件包已被标记为弃用

This package moved to private repository

文档目录17 节

Features
Installation
Usage
Programmatic Usage
Environment Variables
Exporters
Instrumentation
Resource Detectors
Deployment Attributes (applied to Kafka / Socket.IO spans)
Supported Instrumentations
Message Protocol Span Enrichment
M1 Protocol
M2 Protocol
M3 Protocol
Kafka Span Attributes
Build
License

@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

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

版本与发布记录

@eqxjs/nest-opentelemetry 共发布 59 个版本，首次发布于 2024/04/09；过去 12 个月发布了 14 个版本。

版本	发布日期	距今
`3.2.2`latest	2026/03/30	7 个月前
`3.2.1`	2026/03/27	7 个月前
`3.2.0`	2026/03/10	8 个月前
`3.1.3`	2026/02/27	8 个月前
`3.1.2`	2026/02/27	8 个月前
`3.1.1`	2026/02/27	8 个月前

其他发布通道：@eqxjs/nest-opentelemetry → 3.0.2-beta.6，nest-opentelemetry → 3.0.5-beta.2，beta.0 → 3.0.9-beta.0，next → 3.0.9-beta.6。

关于 @eqxjs/nest-opentelemetry 的常见问题

@eqxjs/nest-opentelemetry 是什么？

Opentelemetry Service for nestjs注意：该包已被作者标记为弃用——This package moved to private repository

如何安装 @eqxjs/nest-opentelemetry？

在项目目录运行 npm install @eqxjs/nest-opentelemetry，或使用 pnpm add / yarn add / bun add。

@eqxjs/nest-opentelemetry 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@eqxjs/nest-opentelemetry 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@eqxjs/nest-opentelemetry 可以商用吗？

@eqxjs/nest-opentelemetry 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@eqxjs/nest-opentelemetry 的下载量有多少？

根据 npm 官方下载统计，@eqxjs/nest-opentelemetry 在 2026/10/14 – 2026/11/12 这 30 天内被下载 1,975 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@eqxjs/nest-opentelemetry 还在维护吗？

最新版本 3.2.2 发布于 2026/03/30（7 个月前）；至今共发布 59 个版本，其中过去 12 个月发布了 14 个；首次发布于 2024/04/09。作者已将其标记为弃用，新项目建议寻找替代方案。