OpenTelemetry-JS 中自动与手动埋点协同工作的实践指南

自动埋点与手动埋点的协同机制

在OpenTelemetry-JS项目中，自动埋点(通过getNodeAutoInstrumentations)和手动埋点(通过getTracer)可以完美协同工作。这两种方式本质上都是向同一个TracerProvider注册Span数据，最终会被相同的Exporter统一处理。

典型问题排查

当发现自动埋点数据能正常上报而手动埋点数据丢失时，需要重点关注以下几个方面：

1. TracerProvider注册检查：确保手动埋点使用的Tracer来自SDK注册的TracerProvider，而不是NoopTracerProvider。

2. Exporter配置验证：建议先使用ConsoleExporter进行双重验证，确认两种埋点方式生成的Span都能正常输出到控制台。

3. 上下文传播问题：手动创建的Span需要正确维护上下文关系，特别是当它们嵌套在自动埋点的Span中时。

SDK初始化方式的选择

OpenTelemetry-JS提供了两种初始化方式：

1. NodeSDK简化方式：通过@opentelemetry/sdk-node包提供的封装接口，适合大多数标准场景。

2. 直接配置TracerProvider：提供更细粒度的控制能力，适合需要自定义处理器、采样器或特殊资源配置的场景。

Honeycomb数据缺失的深度排查

针对Honeycomb数据接收异常的情况，建议采取以下诊断步骤：

1. 启用调试日志：设置OTEL_LOG_LEVEL=debug环境变量获取详细输出。

2. 检查Span属性：确保手动Span包含必要的资源属性（如service.name）。

3. 网络传输验证：使用网络抓包工具确认OTLP协议数据是否包含两种Span。

4. Honeycomb查询优化：尝试调整查询时间范围和过滤条件，排除显示层面的问题。

最佳实践建议

1. 统一初始化路径：避免混合使用NodeSDK和手动TracerProvider注册。

2. 上下文管理：对于手动Span，确保正确处理父子关系和使用startActiveSpan。

3. 环境隔离：在测试环境先验证完整链路，再部署到生产环境。

通过系统性地应用这些方法和原则，可以确保OpenTelemetry-JS中的各种埋点方式协同工作，为分布式系统提供完整的可观测性数据。