用途
otel-js 是一套针对 Node.js 应用的 OpenTelemetry（OTel）接入技能，用于为服务添加分布式追踪、指标（metrics）和日志（logs）遥测能力。核心思路是：只需对 Node.js 服务埋点一次，遥测数据即可发送到任意后端（Jaeger、Grafana Tempo、Datadog、Honeycomb）。自动埋点可在不修改代码的情况下捕获 HTTP、数据库和 gRPC 调用。
主要能力
- 自动埋点（Auto-Instrumentation）：通过 @opentelemetry/auto-instrumentations-node 自动覆盖 HTTP、Express、Fastify、PostgreSQL、Redis、MongoDB、gRPC 等库的调用。
- 手动埋点（Custom Spans）：使用 @opentelemetry/api 的 tracer 为业务逻辑（如订单处理、支付流程）创建自定义 Span，可设置属性、记录异常、设置状态码。
- 指标导出：使用 OTLPMetricExporter 与 PeriodicExportingMetricReader，按固定间隔（示例为 30000 毫秒）导出指标。
- 追踪导出：使用 OTLPTraceExporter 将追踪数据导出到 OTLP HTTP 端点。
- 资源配置：通过 Resource 设置服务名称（ATTR_SERVICE_NAME）与服务版本（ATTR_SERVICE_VERSION）等语义约定属性。
- 优雅关闭：监听 SIGTERM 调用 sdk.shutdown()。
使用方式
第一步：安装依赖（自动埋点）。
npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node \
@opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http
然后在应用代码之前导入 instrumentation 配置。示例使用 NodeSDK 配置 resource、traceExporter、metricReader 和 instrumentations，其中可对特定库做配置，例如对 @opentelemetry/instrumentation-http 设置 ignoreIncomingPaths: ['/health', '/ready'] 以不追踪健康检查，启用 Express、pg、Redis 等埋点。
第二步：为业务逻辑添加自定义 Span。示例中 tracer 名称为 'order-service'，在 processOrder 中通过 tracer.startActiveSpan 创建名为 processOrder 的 Span，设置 order.id 属性；在内部为支付创建子 Span chargePayment，设置 payment.provider 与 payment.id 属性；成功后设置 order.status 与 payment.id 并将状态设为 SpanStatusCode.OK；异常时调用 span.recordException(err) 并设置 SpanStatusCode.ERROR 与 message，最后在 finally 中结束 Span。
第三步：运行。需先加载 instrumentation，再启动应用：
node --import ./instrumentation.ts src/server.ts
或在 package.json 中配置：
"start": "node --import ./instrumentation.ts dist/server.js"
适用场景
- 为 Node.js 服务建立可观测性，统一采集追踪与指标。
- 需要自动监控 HTTP、Express、Fastify、数据库（PostgreSQL、Redis、MongoDB）和 gRPC 调用，且不希望侵入业务代码。
- 需要对订单处理、支付流程等关键业务逻辑进行精细化追踪。
- 希望将遥测数据发送到 OTLP collector（如 Grafana Alloy、OTel Collector），再路由到多个后端。
限制与注意事项
- 必须在应用代码之前导入 instrumentation——自动埋点会在导入时对相关库打补丁。
- 使用 --import 标志（ESM）或 -r 标志（CJS）优先加载 instrumentation。
- 自动埋点只覆盖基础设施层，业务逻辑（如订单处理、支付流程）需要自行添加自定义 Span。
- 遥测需发送到 OTLP collector（如 Grafana Alloy、OTel Collector）才能路由到多个后端。
- 示例代码中的端点、间隔、属性名等以资料为准；其他收费、价格、平台支持等信息暂未提供。