腾讯云增强版 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：下载探针
步骤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=myTokenexport OTEL_EXPORTER_OTLP_ENDPOINT=http://pl-demo.ap-guangzhou.apm.tencentcs.com:4317
Jetty
在
<jetty_home\\>/bin/jetty.sh启动脚本中添加以下内容：JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/opentelemetry-javaagent.jar"export OTEL_RESOURCE_ATTRIBUTES=service.name=myService,token=myTokenexport 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 服务端上报监控数据。在有正常流量的情况下，控制台 应用性能监控 > 应用监控 > 应用列表 中将展示接入的应用，控制台应用详情 > 实例监控中将展示接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待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 中添加一些 Attributesspan.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(); } }
查看自定义埋点结果
自定义实例名称（可选）
当多个应用进程使用相同应用名接入 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
是
否
本页内容是否解决了您的问题？