tencent cloud

文档反馈

通过腾讯云增强版 OpenTelemetry Java 探针接入(推荐)

最后更新时间:2024-11-01 17:52:57
    腾讯云增强版 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 服务端上报监控数据。在有正常流量的情况下,控制台 应用性能监控 > 应用监控 > 应用列表 中将展示接入的应用,控制台应用详情 > 实例监控中将展示接入的应用实例。由于可观测数据的处理存在一定延时,如果接入后在控制台没有查询到应用或实例,请等待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。

    自定义实例名称(可选)

    当多个应用进程使用相同应用名接入 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
    
    联系我们

    联系我们,为您的业务提供专属服务。

    技术支持

    如果你想寻求进一步的帮助,通过工单与我们进行联络。我们提供7x24的工单服务。

    7x24 电话支持