tencent cloud

通过腾讯云增强版 OpenTelemetry Java 探针接入（推荐）
下载PDF
最后更新时间：2025-10-13 19:10:48
通过腾讯云增强版 OpenTelemetry Java 探针接入（推荐）
最后更新时间： 2025-10-13 19:10:48
下载PDF
腾讯云增强版 OpenTelemetry Java 探针（TencentCloud-OTel Java Agent）基于开源社区的 OpenTelemetry-java-instrumentation 进行二次开发，遵循 Apache License 2.0 协议，在探针包中对 OpenTelemetry License 进行了引用。在开源探针的基础上，腾讯云增强版 OpenTelemetry Java 探针在埋点密度、高阶诊断、性能保护、企业级能力等方面做了重要的增强。
说明：
OpenTelemetry 是工具、API 和 SDK 的集合，用来检测、生成、收集和导出遥测数据（指标、日志和跟踪），帮助用户分析软件的性能和行为。关于 OpenTelemetry 的更多信息请参考 OpenTelemetry 官方网站。
OpenTelemetry 社区活跃，技术更迭迅速，广泛兼容主流编程语言、组件与框架，为云原生微服务以及容器架构的链路追踪能力广受欢迎。
本文将通过相关操作介绍如何通过腾讯云增强版 OpenTelemetry 探针接入 Java 应用。

前提条件

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

步骤1：获取接入点和 Token

1. 登录 腾讯云可观测平台 控制台。
2. 在左侧菜单栏中选择应用性能监控 > 应用列表，单击接入应用。
3. 在右侧弹出的接入应用抽屉框中，单击 Java 语言。
4. 在接入 Java 应用页面，选择您所要接入的地域以及业务系统。
5. 选择接入协议类型为 OpenTelemetry。
6. 上报方式选择您所想要的上报方式，获取您的接入点和 Token。
说明：
内网上报：使用此上报方式，您的服务需运行在腾讯云 VPC。通过 VPC 直接联通，在避免外网通信的安全风险同时，可以节省上报流量开销。
外网上报：当您的服务部署在本地或非腾讯云 VPC 内，可以通过此方式上报数据。请注意外网通信存在安全风险，同时也会造成一定上报流量费用。

步骤2：下载探针

请进入 探针（Agent）版本信息 下载探针，推荐下载最新版本，探针名为 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-guangzhou.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-guangzhou.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-guangzhou.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-guangzhou.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-guangzhou.apm.tencentcs.com:4317
在这种情况下，请确保本地环境和接入点之间的网络连通性，通常可以使用外网上报接入点地址。
其他应用服务器
请参考对应的配置规范挂载探针，并添加 Java 启动参数或环境变量。

接入验证

完成3个接入步骤后，启动 Java 应用，应用程序将挂载探针，并连接到 APM 服务端上报监控数据。在有正常流量的情况下，应用性能监控 > 应用列表 中将展示接入的应用。单击应用名称/ID 进入应用详情页，再选择实例分析，即可看到接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待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。

在代码中获取 TraceId（可选）

通过 OpenTelemetry-API，可以在应用代码中获取当前的 Span，或者对当前的 Span 增加新的属性。
说明：
腾讯云增强版 Java 探针2.1-20240701及以上版本支持通过 OpenTelemetry API 对当前 Span 进行操作。

引入 OpenTelemetry API 依赖

<dependencies>
    <!-- 其他依赖 -->
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
        <version>1.35.0</version>
    </dependency>
</dependencies>

获取当前的 Span，并增加新的属性

Span span = Span.current(); // 通过静态方法获取当前 Span
String traceId = span.getSpanContext().getTraceId(); // 获取 TraceId
String spanId = span.getSpanContext().getSpanId(); // 获取 SpanId
span.setAttribute("myKey", "myValue"); // 为当前的 Span 增加新的属性

自定义实例名称（可选）

当多个应用进程使用相同应用名接入 APM 以后，在 APM 中会表现为相同应用下的多个应用实例。在大多数场景下，IP 地址都可以作为应用实例的唯一标识，但如果系统中的 IP 地址存在重复的情况，就需要使用其他唯一标识定义实例名称。例如，系统中的应用直接通过 Docker 启动，没有基于 Kubernetes 部署，就有可能存在容器 IP 地址重复的情况，用户可以将实例名称设置为主机 IP + 容器 IP 的形式。
参考如下脚本，在接入 APM 需要用到的 JVM 启动参数 -Dotel.resource.attributes 中，加上 host.name 字段。
-Dotel.resource.attributes=service.name=my_service,token=my_demo_token,host.name=10.10.1.1_192.168.1.2

本页内容是否解决了您的问题？
您也可以 联系销售 或 提交工单 以寻求帮助。
是
否

文档反馈