通过增强版 OpenTelemetry Java 探针接入（推荐）

增强版 OpenTelemetry Java 探针（Cloud Platform-OTel Java Agent）基于开源社区的 OpenTelemetry-java-instrumentation 进行二次开发，遵循 Apache License 2.0 协议，在探针包中对 OpenTelemetry License 进行了引用。在开源探针的基础上，增强版 OpenTelemetry Java 探针在埋点密度、高阶诊断、性能保护、企业级能力等方面做了重要的增强。

说明：

• OpenTelemetry 是工具、API 和 SDK 的集合，用来检测、生成、收集和导出遥测数据（指标、日志和跟踪），帮助用户分析软件的性能和行为。关于 OpenTelemetry 的更多信息请参考 OpenTelemetry 官方网站。
• OpenTelemetry 社区活跃，技术更迭迅速，广泛兼容主流编程语言、组件与框架，为云原生微服务以及容器架构的链路追踪能力广受欢迎。

本文将通过相关操作介绍如何通过增强版 OpenTelemetry 探针接入 Java 应用。

前提条件

请参考 OpenTelemetry 方案支持的组件和框架，确保 Java 版本和应用服务器在探针支持的范围内。对于自动埋点支持的依赖库和框架，在接入成功后即可完成数据上报，不需要修改代码。同时，增强版 OpenTelemetry Java 探针遵循了 OpenTelemetry 协议标准，如果自动埋点不满足您的场景，或者需要增加业务层埋点，请参考 自定义埋点，使用 OpenTelemetry API 进行自定义埋点。

步骤1：获取接入点和 Token

1. 在左侧菜单栏中选择应用性能监控 > 应用监控，单击应用列表 > 接入应用。
2. 在右侧弹出的数据接入抽屉框中，单击 Java 语言。
3. 在接入 Java 应用页面，选择您所要接入的地域以及业务系统。
4. 选择接入协议类型为 OpenTelemetry。
5. 获取接入点和 Token。

步骤2：下载探针

在控制台下载探针并保存，探针名为 opentelemetry-javaagent.jar。

步骤3：修改上报参数

接入 Java 应用需要用到如下3个 JVM 启动参数：

-javaagent:<javaagent>
-Dotel.resource.attributes=service.name=<serviceName>,token=<token>
-Dotel.exporter.otlp.endpoint=<endpoint> 

在执行 Java 命令的时候，请确保这3个 JVM 启动参数放在 -jar 之前。对于无法直接指定 JVM 启动参数的应用，-Dotel.resource.attributes 系统参数可以替换为 OTEL_RESOURCE_ATTRIBUTES 环境变量，-Dotel.exporter.otlp.endpoint 系统参数可以替换为 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量。对应的字段说明如下：

• <javaagent> ：探针对应的本地文件路径。

• <serviceName> ：应用名，多个使用相同应用名接入的进程，在 APM 中会表现为相同应用下的多个实例。对于 Spring Cloud 或 Dubbo 应用，应用名通常和服务名保持一致。最长63个字符，只能包含小写字母、数字及分隔符“ - ”，且必须以小写字母开头，数字或小写字母结尾。

• <token> ：步骤1中拿到业务系统 Token。

• <endpoint> ：步骤1中拿到的接入点。
  下述内容以探针路径为 /path/to/opentelemetry-javaagent.jar，应用名为 myService，业务系统 Token 为 myToken，接入点为http://pl-demo.ap-*${Region}*.apm.tencentcs.com:4317为例，介绍不同环境的完整启动脚本：

• JAR File 或 Spring Boot

  java -javaagent:/path/to/opentelemetry-javaagent.jar \
  -Dotel.resource.attributes=service.name=myService,token=myToken\
  -Dotel.exporter.otlp.endpoint=http://pl-demo.ap-${Region}.apm.tencentcs.com:4317 \
  -jar SpringCloudApplication.jar
  

• Linux Tomcat 7/Tomcat 8
  在 {TOMCAT_HOME}/bin/setenv.sh 配置文件添加以下内容：

  CATALINA_OPTS="$CATALINA_OPTS -javaagent:/path/to/opentelemetry-javaagent.jar"
  export OTEL_RESOURCE_ATTRIBUTES=service.name=myService,token=myToken
  export OTEL_EXPORTER_OTLP_ENDPOINT=http://pl-demo.ap-${Region}.apm.tencentcs.com:4317
  

  如果您的 Tomcat 没有 setenv.sh 配置文件，请参考 Tomcat 官方文档 初始化 setenv.sh 配置文件，或者使用其他方式添加 Java 启动参数以及环境变量。

• Jetty
  在<jetty_home\>/bin/jetty.sh启动脚本中添加以下内容：

  JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/opentelemetry-javaagent.jar"
  export OTEL_RESOURCE_ATTRIBUTES=service.name=myService,token=myToken
  export OTEL_EXPORTER_OTLP_ENDPOINT=http://pl-demo.ap-${Region}.apm.tencentcs.com:4317
  

• IDEA
  在 IDEA 中本地调试 Java 应用时，可在 Run Configuration 中配置 VM options，参数配置如下：

  -javaagent:"/path/to/opentelemetry-javaagent.jar" 
  -Dotel.resource.attributes=service.name=myService,token=myToken
  -Dotel.exporter.otlp.endpoint=http://pl-demo.ap-${Region}.apm.tencentcs.com:4317 
  

  在这种情况下，请确保本地环境和接入点之间的网络连通性，通常可以使用外网上报接入点地址。

• 其他应用服务器
  请参考对应的配置规范挂载探针，并添加 Java 启动参数或环境变量。

接入验证

完成3个接入步骤后，启动 Java 应用，应用程序将挂载探针，并连接到 APM 服务端上报监控数据。在有正常流量的情况下，控制台应用性能监控 > 应用监控 > 应用列表中将展示接入的应用，控制台应用详情 > 实例监控中将展示接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待30秒左右。

自定义埋点 （可选）

当自动埋点不满足您的场景或者需要增加业务层埋点时，您可参照下述内容，使用 OpenTelemetry API 添加自定义埋点。本文仅展示最基本的自定义埋点方式，OpenTelemetry 社区提供了更多灵活的自定义埋点方式，具体使用方法可参考 OpenTelemetry 官方文档。

引入 OpenTelemetry API 依赖

<dependencies>
    <!-- 其他依赖 -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
    </dependency>
</dependencies>
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.9.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

获取 Tracer

在需要进行埋点的代码中，可以通过如下代码获取 Tracer 对象：

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Tracer;

public class AcquireTracerDemo {
    public void acquireTracer() {
        // scope 用于定义埋点范围，一般情况下可以直接使用类名，关于Scope的更多信息，请参考 OpenTelemetry 官方文档
        String scope = this.getClass().getName();
        OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
        Tracer tracer = openTelemetry.getTracer(scope);
    }
}

设置对业务方法进行埋点

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;

// Trace 对象可以在业务方法中获取，或者通过参数传入业务方法
public void doTask(Tracer tracer) {
    // 创建一个 Span
    Span span = tracer.spanBuilder("doTask").startSpan();
    // 在 Span 中添加一些 Attributes
    span.setAttribute("RequestId", "5fc92ff1-8ca8-45f4-8013-24b4b5257666");
    // 将此 Span 设置为当前的Span
    try (Scope scope = span.makeCurrent()) {
        doSubTask1();
        doSubTask2();
    } catch (Throwable t) {
        // 处理异常，异常信息将记录到 Span 的对应事件中
        span.recordException(t);
        span.setStatus(StatusCode.ERROR);
        throw t;
    } finally {
        // 结束 Span
        span.end();
    }
}

查看自定义埋点结果

在应用性能监控 > 调用查询中，找到相关的调用链，点击 Span ID，进入链路详情页面，即可查到通过自定义埋点新增的 Span。