注意：说明：
这篇会通过相关操作介绍如何通过腾讯云增强版 OpenTelemetry 探针接入 Java 应用。
一、前提条件
请参考 增强版 OpenTelemetry Java 探针支持的 Java 版本和框架，确保 Java 版本和应用服务器在探针支持的范围内。对于自动埋点支持的依赖库和框架，在接入成功后即可完成数据上报，不需要修改代码。同时，腾讯云增强版 OpenTelemetry Java 探针遵循了 OpenTelemetry 协议标准，如果自动埋点不满足你的场景，或者需要增加业务层埋点，请参考 自定义埋点，使用 OpenTelemetry API 进行自定义埋点。
二、步骤1：获取接入点和 Token
1. 登录 腾讯云可观测平台 控制台。
2. 在左侧菜单栏中选择应用性能监控 > 应用列表，单击接入应用。
3. 在右侧弹出的接入应用抽屉框中，单击 Java 语言。
4. 在接入 Java 应用页面，选择你所要接入的地域以及业务系统。
5. 选择接入协议类型为 OpenTelemetry。
6. 选择你所想要的上报方式，获取你的接入点和 Token。
注意：说明：
注意：由于缺少对 ALPN 的原生支持，8u252之前的 Java 版本不支持 HTTPS 接入点。对于 Java 版本低于8u252的存量应用，请使用 HTTP 接入点。
三、步骤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中拿到的接入点。
注意：说明：
注意：上述列出的字段均为必填（Required）。
下述内容以探针路径为 /path/to/opentelemetry-javaagent.jar，应用名为 myService，业务系统 Token 为 myToken，接入点为 http://pl-demo.ap-guangzhou.apm.tencentcs.com:4319 为例，介绍不同环境的完整启动脚本。
·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:4319 \\ -jar SpringCloudApplication.jar
·Tomcat
在 {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:4319
如果你的 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=myTokenexport OTEL_EXPORTER_OTLP_ENDPOINT=http://pl-demo.ap-guangzhou.apm.tencentcs.com:4319
·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:4319
在这种情况下，请确保本地环境和接入点之间的网络连通性，通常可以使用外网上报接入点地址。
·其他应用服务器
请参考对应的配置规范挂载探针，并添加 Java 启动参数或环境变量。
五、接入验证
完成3个接入步骤后，启动 Java 应用，应用程序将挂载探针，并连接到 APM 服务端上报监控数据。在有正常流量的情况下，应用性能监控 > 应用列表 中将展示接入的应用，单击应用名称/ID 进入应用详情页。
再选择实例分析，即可看到接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待30秒左右。
六、自定义埋点 （可选）
当自动埋点不满足你的场景或者需要增加业务层埋点时，你可参照下述内容，使用 OpenTelemetry API 添加自定义埋点。这篇仅展示最基本的自定义埋点方式，OpenTelemetry 社区提供了更多灵活的自定义埋点方式，具体使用方法可参考 OpenTelemetry 产品文档。
注意：说明：
注意：腾讯云增强版 Java 探针2.1-20240701及以上版本支持通过 OpenTelemetry API 自定义埋点。
七、引入 OpenTelemetry API 依赖
<dependencies> <!– 其他依赖 –> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.35.0</version> </dependency>
</dependencies>
八、获取 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 class TaskDemo { 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，并增加新的属性
public class Demo { public void method() { Span span = Span.current(); 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_token,host.name=10.10.1.1_192.168.1.2