腾讯云增强版 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
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: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=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 服务端上报监控数据。在有正常流量的情况下，
应用性能监控 > 应用列表 中将展示接入的应用，点击
应用名称/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 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(); // 通过静态方法获取当前 SpanString traceId = span.getSpanContext().getTraceId(); // 获取 TraceIdString spanId = span.getSpanContext().getSpanId(); // 获取 SpanIdspan.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
编辑推荐：
下一篇：
相关推荐
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
雷神推出 MIX PRO II 迷你主机：基于 Ultra 200H，玻璃上盖 + ARGB 灯效
2 月 9 日消息，雷神 (THUNDEROBOT) 现已宣布推出基于英
-
制造商 Musnap 推出彩色墨水屏电纸书 Ocean C：支持手写笔、第三方安卓应用
2 月 10 日消息，制造商 Musnap 现已在海外推出一款 Oce
热文推荐
- 计算机服务器中了360后缀勒索病毒怎么解密，360勒索病毒解密工具
计算机服务器中了360后缀勒索病毒怎么解密，360勒索病毒解密工具
26-03-02 - .PGF文件是什么格式文件?能不能删除?
.PGF文件是什么格式文件?能不能删除?
26-03-02 - 计算机服务器中了halo勒索病毒怎么解密，halo勒索病毒解密恢复工具
计算机服务器中了halo勒索病毒怎么解密，halo勒索病毒解密恢复工具
26-03-02 - 计算机服务器中了mallox勒索病毒怎么解密，mallox勒索病毒解密恢复工具
- 企业计算机服务器中了faust勒索病毒怎么解密，faust勒索病毒解密恢复
- .TDL是什么格式文件?.TDL如何打开?
.TDL是什么格式文件?.TDL如何打开?
26-03-02 - 虚拟机服务器中了lockbit3.0勒索病毒怎么解密，lockbit3.0勒索病毒解密恢复工具
- .kdh是什么文件?.kdh如何打开?
.kdh是什么文件?.kdh如何打开?
26-03-02 - 电脑提示“没有找到comres.dll”怎么解决?
电脑提示“没有找到comres.dll”怎么解决?
26-03-02 - .3DXML是什么格式文件? .3DXML如何打开?
.3DXML是什么格式文件? .3DXML如何打开?
26-03-02
