腾讯云增强版 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
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 服务端上报监控数据。在有正常流量的情况下,控制台 应用性能监控 > 应用监控 > 应用列表 中将展示接入的应用,控制台应用详情 > 实例监控中将展示接入的应用实例。由于可观测数据的处理存在一定延时,如果接入后在控制台没有查询到应用或实例,请等待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() {
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;
public void doTask(Tracer tracer) {
Span span = tracer.spanBuilder("doTask").startSpan();
span.setAttribute("RequestId", "5fc92ff1-8ca8-45f4-8013-24b4b5257666");
try (Scope scope = span.makeCurrent()) {
doSubTask1();
doSubTask2();
} catch (Throwable t) {
span.recordException(t);
span.setStatus(StatusCode.ERROR);
throw t;
} finally {
span.end();
}
}
查看自定义埋点结果
在 应用性能监控 > 调用查询 中,找到相关的调用链,点击 Span ID,进入链路详情页面,即可查到通过自定义埋点新增的 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
本页内容是否解决了您的问题?