五分钟接入 OpenTelemetry：从零采集 Trace 与指标

很多团队对可观测性的第一道坎是"接入太麻烦"。其实用 OpenTelemetry（OTel）从零到看到第一条 Trace，只要几分钟。本文以 Java 服务为例走一遍完整流程，配置片段可以直接复制。

第一步：引入依赖并初始化 SDK

在 pom.xml 里加入 OTel SDK 与导出器，再写一个初始化类。核心是配置采样率、资源属性（service.name）和导出端点：

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
  <version>1.38.0</version>
</dependency>

Resource resource = Resource.getDefault()
    .merge(Resource.create(Attributes.of(
        ResourceAttributes.SERVICE_NAME, "order-svc")));

SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
    .setResource(resource)
    .addSpanProcessor(BatchSpanProcessor.builder(
        OtlpHttpSpanExporter.builder()
            .setEndpoint("https://ob.jjhub.cn/v1/traces")
            .build()).build())
    .setSampler(Sampler.parentBased(Sampler.traceIdRatioBased(0.1)))
    .build();

service.name 是后续检索和告警分组的关键字段，务必唯一且稳定，别用带版本号的临时名。

第二步：给关键路径埋点

框架自动埋点能覆盖 HTTP 请求，但业务语义要靠手动 Span 补上。以订单支付为例：

Span span = tracer.spanBuilder("payment.execute")
    .setAttribute("order.id", orderId)
    .setAttribute("payment.channel", channel)
    .startSpan();
try (Scope scope = span.makeCurrent()) {
    // 业务逻辑
    span.setStatus(StatusCode.OK);
} catch (Exception e) {
    span.setStatus(StatusCode.ERROR, "payment failed");
    span.recordException(e);
    throw e;
} finally {
    span.end();
}

属性命名建议统一小写点分格式（payment.channel），后续做指标聚合和检索过滤会省很多事。

第三步：采集指标

指标用 Meter API，不依赖 Trace。下面是一个计数器，统计支付成功次数：

LongCounter successCounter = meter
    .counterBuilder("payment.success.total")
    .setDescription("支付成功总数")
    .setUnit("1")
    .build();

successCounter.add(1, Attributes.of(
    AttributeKey.stringKey("channel"), channel));

计数器适合累计值；耗时、队列长度这类要观测瞬时分布的量，用 Histogram 更合适。

第四步：后端配置与验证

在 OBSERVE 控制台新建数据源，填入 OTLP 端点与令牌；服务启动后请求几次接口，回到"链路追踪"页按 service.name = order-svc 过滤，应能看到完整 Span 瀑布。看不到时按顺序查三处：端点是否可达、采样率是否过低、service.name 是否写错。

一条建议：先把采样率调高（如 0.5）验证链路完整，再降到生产可承受的值，别一上来就 0.01 然后怀疑接入失败。