otel-instrumentation

OpenTelemetry 插桩指南

关于实现高质量、高性价比 OpenTelemetry 遥测的专家指导。

规则与快速参考

用例 / 规则	说明
telemetry	入口 — 信号类型、关联与导航
resolve-values	从代码库中解析配置值
verify-dependencies	添加插桩包前，验证其是否存在及版本是否可用
resources	资源属性 — 服务身份与环境
k8s	Kubernetes 部署 — downward API、pod 规范
spans	Span — 命名、类型、状态与规范
logs	日志 — 结构化日志、严重级别、Trace 关联
metrics	指标 — 仪器类型、命名、单位、基数
sensitive-data	敏感数据 — 防止 PII、清理、脱敏
capture-database-query-parameters	各语言的预处理语句参数捕获（Java、.NET、Python、Node.js、Go）
validation	遥测验证 — 部署后验证清单
nodejs	Node.js 插桩设置
go	Go 插桩设置
python	Python 插桩设置
java	Java 插桩设置
scala	Scala 插桩设置
dotnet	.NET 插桩设置
ruby	Ruby 插桩设置
php	PHP 插桩设置
browser	浏览器插桩设置
nextjs	Next.js 全栈插桩（App Router）

官方文档

• OpenTelemetry 文档
• 语义约定
• Dash0 集成中心

入门

从头开始为应用添加插桩时，请按以下步骤操作：

1. 选择 SDK 规则 — 从上表中选择对应语言的规则（例如，nodejs、python）。
2. 设置资源属性 — 按照 resources 定义服务身份与环境。
3. 添加 Span、指标和日志 — 按照 spans、metrics 和 logs 为代码添加插桩。
4. 保护敏感数据 — 按照 sensitive-data 在导出前清除 PII。
5. 验证 — 使用 validation 中的清单，确认遥测数据已到达后端。

下面的代码片段展示了一个包含属性和状态的完整 Node.js Span — 有关 SDK 初始化、导出器配置和自动插桩的完整设置，请参阅 nodejs：

import { trace, SpanStatusCode } from '@opentelemetry/api';
const tracer = trace.getTracer('my-service', '1.0.0');

tracer.startActiveSpan('operation-name', async (span) => {
  try {
    span.setAttribute('user.id', userId);
    span.setAttribute('order.id', orderId);

    const result = await processOrder(orderId);

    span.setAttribute('order.status', result.status);
    span.setStatus({ code: SpanStatusCode.OK });
    return result;
  } catch (err) {
    // Record the exception as a structured log record, not span.recordException — see rules/spans.md
    span.setStatus({ code: SpanStatusCode.ERROR, message: `${err.name}: ${err.message}` });
    const spanContext = span.spanContext();
    logger.error('operation-name.failed', {
      'trace_id': spanContext.traceId,
      'span_id': spanContext.spanId,
      'exception.type': err.name,
      'exception.message': err.message,
      'exception.stacktrace': err.stack,
    });
    throw err;
  } finally {
    span.end();
  }
});

核心原则

信号密度优先于数量

每条遥测数据都应满足以下三个目的之一：

• 检测 - 帮助发现问题
• 定位 - 帮助确定问题所在
• 解释 - 帮助理解问题发生的原因

如果不满足其中任何一个目的，就不要发送。

在管道中采样，而不是在 SDK 中采样

请在每个 SDK 中显式设置 AlwaysOn 采样器（OTEL_TRACES_SAMPLER=always_on）。 这会覆盖 OpenTelemetry 的默认设置 ParentBased(root=AlwaysOn)；在此设置下，信任边界之外的调用方可以通过 traceparent 标头悄无声息地关闭服务的追踪。 也不要配置基于比例的 SDK 采样器——它们会在请求结果尚未确定时做出不可逆的决策。 将所有采样交由Collector处理，以便在不重新部署应用的情况下集中更改策略。 有关完整理由及 ParentBased 可接受的条件，请参阅 SDK 采样。

SDK (AlwaysOn, set explicitly)  →  Collector (sampling)  →  Backend (retention)
             ↓                           ↓                       ↓
       All spans                   Head or tail            Storage policies
       exported                    sampling applied