通过OpenTelemetry为Java应用埋点并上报链路数据_应用实时监控服务(ARMS)-阿里云帮助中心

通过OpenTelemetry为应用埋点并上报链路数据至可观测链路 OpenTelemetry 版后，可观测链路 OpenTelemetry 版即可开始监控应用，您可以查看应用拓扑、调用链路、异常事务、慢事务和SQL分析等一系列监控数据。本文介绍如何使用OpenTelemetry Java Agent/SDK进行自动或手动埋点并上报数据。

前提条件

获取接入点信息

登录ARMS控制台，在左侧导航栏单击接入中心。
在服务端应用区域单击OpenTelemetry卡片。
在弹出的OpenTelemetry面板中选择数据需要上报的地域。
说明
初次接入的地域将会自动进行资源初始化。
选择连接方式和上报方式，然后复制接入点信息。
- 连接方式：若您的服务部署在阿里云上，且所属地域与选择的接入地域一致，推荐使用阿里云内网方式，否则选择公网方式。
- 上报方式：根据客户端支持的协议类型选择HTTP或gRPC协议上报数据。

背景信息

OpenTelemetry Java Agent支持自动埋点的Java框架列表如下，完整信息请参考Supported Libraries and Versions。

展开查看支持监控的Java框架

框架	框架版本限制
Akka Actors	2.5+
Akka HTTP	10.0+
Apache Axis2	1.6+
Apache Camel	2.20+（暂不支持3.x）
Apache DBCP	2.0+
Apache CXF JAX-RS	3.2+
Apache CXF JAX-WS	3.0+
Apache Dubbo	2.7+
Apache HttpAsyncClient	4.1+
Apache HttpClient	2.0+
Apache Kafka Producer/Consumer API	0.11+
Apache Kafka Streams API	0.11+
Apache MyFaces	1.2+（暂不支持3.x）
Apache Pulsar	2.8+
Apache RocketMQ gRPC/Protobuf-based Client	5.0+
Apache RocketMQ Remoting-based Client	4.8+
Apache Struts 2	2.3+
Apache Tapestry	5.4+
Apache Wicket	8.0+
Armeria	1.3+
AsyncHttpClient	1.9+
AWS Lambda	1.0+
AWS SDK	1.11.x和2.2+
Azure Core	1.14+
Cassandra Driver	3.0+
Couchbase Client	2.0+和3.1+
c3p0	0.9.2+
Dropwizard Metrics	4.0+（默认禁用）
Dropwizard Views	0.7+
Eclipse Grizzly	2.3+
Eclipse Jersey	2.0+（暂不支持3.x）
Eclipse Jetty HTTP Client	9.2+（暂不支持10+）
Eclipse Metro	2.2+
Eclipse Mojarra	1.2+（暂不支持3.x）
Elasticsearch API Client	7.16+和8.0+
Elasticsearch REST Client	5.0+
Elasticsearch Transport Client	5.0+
Finatra	2.9+
Geode Client	1.4+
Google HTTP Client	1.19+
Grails	3.0+
GraphQL Java	12.0+
gRPC	1.6+
Guava ListenableFuture	10.0+
GWT	2.0+
Hibernate	3.3+
Hibernate Reactive	1.0+
HikariCP	3.0+
HttpURLConnection	Java 8+
Hystrix	1.4+
Java Executors	Java 8+
Java Http Client	Java 11+
java.util.logging	Java 8+
Java Platform	Java 8+
JAX-RS	0.5+
JAX-RS Client	1.1+
JAX-WS	2.0+（暂不包含3.x）
JBoss Log Manager	1.1+
JDBC	Java 8+
Jedis	1.4+
JMS	1.1+
Jodd Http	4.2+
JSP	2.3+
Kotlin Coroutines	1.0+
Ktor	1.0+
Kubernetes Client	7.0+
Lettuce	4.0+
Log4j 1	1.2+
Log4j 2	2.11+
Logback	1.0+
Micrometer	1.5+
MongoDB Driver	3.1+
Netty	3.8+
OkHttp	2.2+
Oracle UCP	11.2+
OSHI	5.3.1+
Play	2.4+
Play WS	1.0+
Quartz	2.0+
R2DBC	1.0+
RabbitMQ Client	2.7+
Ratpack	1.4+
Reactor	3.1+
Reactor Netty	0.9+
Rediscala	1.8+
Redisson	3.0+
RESTEasy	3.0+
Restlet	1.0+
RMI	Java 8+
RxJava	1.0+
Scala ForkJoinPool	2.8+
Servlet	2.2+
Spark Web Framework	2.3+
Spring Boot	-
Spring Batch	3.0+（暂不支持5.0+）
Spring Cloud Gateway	2.0+
Spring Data	1.8+
Spring Integration	4.1+（暂不支持6.0+）
Spring JMS	2.0+
Spring Kafka	2.7+
Spring RabbitMQ	1.0+
Spring Scheduling	3.1+
Spring RestTemplate	3.1+
Spring Web MVC	3.1+
Spring Web Services	2.0+
Spring WebFlux	5.3+
Spymemcached	2.12+
Tomcat JDBC Pool	8.5+
Twilio	6.6+（暂不支持8.x）
Undertow	1.4+
Vaadin	14.2+
Vert.x Web	3.0+
Vert.x HttpClient	3.0+
Vert.x Kafka Client	3.6+
Vert.x RxJava2	3.5+
Vert.x SQL Client	4.0+
Vibur DBCP	11.0+
ZIO	2.0+

示例Demo

示例代码仓库地址：java-opentelemetry-demo

方法一：使用OpenTelemetry Java Agent自动埋点

OpenTelemetry Java Agent提供了无侵入的接入方式，支持上百种Java框架自动上传Trace数据，详细的Java框架列表，请参见Supported Libraries and Versions。

下载Java Agent。

通过修改Java启动的VM参数上报链路数据。

如果您选择直接上报数据，请将<token>、<endpoint>替换为前提条件中获取的信息。

说明

Http方式不需要设置鉴权Token，仅需设置接入点（endpoint）。

Http方式

java -javaagent:/path/to/opentelemetry-javaagent.jar   //请将路径修改为您文件下载的实际地址。
-Dotel.exporter.otlp.protocol=http/protobuf \
-Dotel.exporter.otlp.traces.endpoint=<traces.endpoint> \   //替换为前提条件中获取到的trace接入点。
-Dotel.exporter.otlp.metrics.endpoint=<metrics.endpoint> \   //替换为前提条件中获取到的metric接入点。
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jar

例如：

java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.exporter.otlp.protocol=http/protobuf \
-Dotel.exporter.otlp.traces.endpoint=http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe****/api/otlp/traces \
-Dotel.exporter.otlp.metrics.endpoint=http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe****/api/otlp/metrics \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jar

gRPC方式

java -javaagent:/path/to/opentelemetry-javaagent.jar \   //请将路径修改为您文件下载的实际地址。
-Dotel.exporter.otlp.protocol=grpc \
-Dotel.exporter.otlp.headers=Authentication=<token> \   //替换为前提条件中获取到的鉴权Token。
-Dotel.exporter.otlp.endpoint=<endpoint> \   //替换为前提条件中获取到的接入点。
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jar

例如：

java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.exporter.otlp.protocol=grpc \
-Dotel.exporter.otlp.headers=Authentication=ggxw4l****@7323a5caae3****_ggxw4l****@53df7ad2afe**** \
-Dotel.exporter.otlp.endpoint=http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090 \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jar

说明

如果您选择使用OpenTelemetry Collector转发，则需删除-Dotel.exporter.otlp.headers=Authentication=<token>并修改<endpoint>为您本地部署的服务地址。

方法二：使用OpenTelemetry Java SDK手动埋点

OpenTelemetry Java SDK是OpenTelemetry Java Agent实现的基础，同时提供了丰富的自定义能力。当OpenTelemetry Java Agent的埋点不满足您的场景或者需要增加一些自定义业务埋点时，可以使用以下方式接入。

引入Maven POM依赖。

<dependencies>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
  </dependency>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-trace</artifactId>
  </dependency>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
  </dependency>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
  </dependency>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-semconv</artifactId>
    <version>1.23.0-alpha</version>
  </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.23.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

获取OpenTelemetry Tracer。

<logical-service-name>为服务名，<host-name>为主机名，请根据您的实际场景配置。
如果您选择直接上报数据，请将以下代码中的<token>替换成前提条件中获取的Token，将<endpoint>替换成对应地域的Endpoint。

package com.alibaba.arms.brightroar.console.util;

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
import io.opentelemetry.context.propagation.ContextPropagators;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.semconv.resource.attributes.ResourceAttributes;

public class OpenTelemetrySupport {

    static {
        // 获取OpenTelemetry Tracer
        Resource resource = Resource.getDefault()
                .merge(Resource.create(Attributes.of(
                        ResourceAttributes.SERVICE_NAME, "<logical-service-name>",
                        ResourceAttributes.HOST_NAME, "<host-name>"
                )));

        SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
                .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
                        .setEndpoint("<endpoint>")
                        .addHeader("Authentication", "<token>")
                        .build()).build())
                .setResource(resource)
                .build();

        OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
                .setTracerProvider(sdkTracerProvider)
                .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
                .buildAndRegisterGlobal();

        tracer = openTelemetry.getTracer("<your_tracer_name>", "1.0.0");
    }

    private static Tracer tracer;

    public static Tracer getTracer() {
        return tracer;
    }

}

参考以下内容修改Controller代码和Service代码。

Controller代码：

package com.alibaba.arms.brightroar.console.controller;

import com.alibaba.arms.brightroar.console.service.UserService;
import com.alibaba.arms.brightroar.console.util.OpenTelemetrySupport;
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

/**
 * 参考文档：
 * 1. https://opentelemetry.io/docs/java/manual_instrumentation/
 */
@RestController
@RequestMapping("/user")
public class UserController {

    @Autowired
    private UserService userService;

    private ExecutorService es = Executors.newFixedThreadPool(5);

    private void biz() {
        Tracer tracer = OpenTelemetrySupport.getTracer();
        Span span = tracer.spanBuilder("biz (manual)")
                .setParent(Context.current().with(Span.current())) // 可选，自动设置
                .startSpan();

        try (Scope scope = span.makeCurrent()) {
            span.setAttribute("biz-id", "111");

            es.submit(new Runnable() {
                @Override
                public void run() {
                    Span asyncSpan = tracer.spanBuilder("async")
                            .setParent(Context.current().with(span))
                            .startSpan();
                    try {
                        Thread.sleep(1000L); // some async jobs
                    } catch (Throwable e) {
                    }
                    asyncSpan.end();
                }
            });

            Thread.sleep(1000); // fake biz logic
            System.out.println("biz done");
            OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
            openTelemetry.getPropagators();
        } catch (Throwable t) {
            span.setStatus(StatusCode.ERROR, "handle biz error");
        } finally {
            span.end();
        }
    }

    private void child(String userType) {
        Span span = OpenTelemetrySupport.getTracer().spanBuilder("child span").startSpan();
        try (Scope scope = span.makeCurrent()) {
            span.setAttribute("user.type", userType);
            System.out.println(userType);
            biz();
        } catch (Throwable t) {
            span.setStatus(StatusCode.ERROR, "handle child span error");
        } finally {
            span.end();
        }
    }

    @RequestMapping("/async")
    public String async() {
        System.out.println("UserController.async -- " + Thread.currentThread().getId());
        Span span = OpenTelemetrySupport.getTracer().spanBuilder("parent span").startSpan();
        span.setAttribute("user.id", "123456");
        try (Scope scope = span.makeCurrent()) {
            userService.async();
            child("vip");
        } catch (Throwable t) {
            span.setStatus(StatusCode.ERROR, "handle parent span error");
        } finally {
            span.end();
        }
        return "async";
    }

}

Service代码：

package com.alibaba.arms.brightroar.console.service;

import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    @Async
    public void async() {
        System.out.println("UserService.async -- " + Thread.currentThread().getId());
        System.out.println("my name is async");
        System.out.println("UserService.async -- ");
    }
}

启动应用。
登录ARMS控制台后，在应用监控 > 应用列表页面选择目标应用，查看链路数据。
说明
语言列显示图标的应用为接入应用监控的应用，显示-图标的应用为接入可观测链路 OpenTelemetry 版的应用。

方法三：同时使用Java Agent和Java SDK埋点

您可以在使用Java Agent获得自动埋点能力的同时，使用Java SDK添加自定义业务埋点。

下载Java Agent。

在方法二的Maven依赖基础上新增以下依赖。

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-extension-annotations</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
    <version>1.23.0-alpha</version>
</dependency>

说明

其中opentelemetry-sdk-extension-autoconfigure完成了SDK的自动配置，将Java Agent的配置传递到Java SDK中。

展开查看完整的Maven POM依赖

<dependencies>
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>2.1.3</version>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-trace</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-extension-annotations</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-exporter-otlp</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-semconv</artifactId>
        <version>1.23.0-alpha</version>
    </dependency>
    <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-sdk-extension-autoconfigure</artifactId>
        <version>1.23.0-alpha</version>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.23.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

获取OpenTelemetry Tracer。
同时使用Java Agent和Java SDK埋点时，无需再使用方法二中的OpenTelemetrySupport类获取Tracer。
```
OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
Tracer tracer = openTelemetry.getTracer("instrumentation-library-name", "1.0.0");
```

参考以下内容修改Controller代码和Service代码。

Controller代码如下，建议使用代码中的第一种和第二种方式。

package com.alibaba.arms.brightroar.console.controller;

import com.alibaba.arms.brightroar.console.service.UserService;
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Context;
import io.opentelemetry.context.Scope;
import io.opentelemetry.extension.annotations.SpanAttribute;
import io.opentelemetry.extension.annotations.WithSpan;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

/**
* 参考文档：
* 1. https://opentelemetry.io/docs/java/manual_instrumentation/
*/
@RestController
    @RequestMapping("/user")
    public class UserController {

        @Autowired
        private UserService userService;

        private ExecutorService es = Executors.newFixedThreadPool(5);

        // 第一种：自动埋点，基于 API 手工添加信息
        @RequestMapping("/async")
        public String async() {
            System.out.println("UserController.async -- " + Thread.currentThread().getId());
            Span span = Span.current();
            span.setAttribute("user.id", "123456");
            userService.async();
            child("vip");
            return "async";
        }

        // 第二种：通过注解创建埋点
        @WithSpan
        private void child(@SpanAttribute("user.type") String userType) {
            System.out.println(userType);
            biz();
        }

        // 第三种：获得 Tracer 纯手工埋点
        private void biz() {
            Tracer tracer = GlobalOpenTelemetry.get().getTracer("tracer");
            Span span = tracer.spanBuilder("biz (manual)")
                .setParent(Context.current().with(Span.current())) // 可选，自动设置
                .startSpan();

            try (Scope scope = span.makeCurrent()) {
                span.setAttribute("biz-id", "111");

                es.submit(new Runnable() {
                    @Override
                    public void run() {
                        Span asyncSpan = tracer.spanBuilder("async")
                            .setParent(Context.current().with(span))
                            .startSpan();
                        try {
                            Thread.sleep(1000L); // some async jobs
                        } catch (Throwable e) {
                        }
                        asyncSpan.end();
                    }
                });

                Thread.sleep(1000); // fake biz logic
                System.out.println("biz done");
                OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
                openTelemetry.getPropagators();
            } catch (Throwable t) {
                span.setStatus(StatusCode.ERROR, "handle biz error");
            } finally {
                span.end();
            }
        }

    }

Service代码：

package com.alibaba.arms.brightroar.console.service;

import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;

@Service
public class UserService {

    @Async
    public void async() {
        System.out.println("UserService.async -- " + Thread.currentThread().getId());
        System.out.println("my name is async");
        System.out.println("UserService.async -- ");
    }
}

通过修改Java启动的VM参数上报链路数据。

-javaagent:/path/to/opentelemetry-javaagent.jar    //请将路径修改为您文件下载的实际地址。
-Dotel.resource.attributes=service.name=<appName>     //<appName> 为应用名。
-Dotel.exporter.otlp.headers=Authentication=<token>
-Dotel.exporter.otlp.endpoint=<endpoint>

如果您选择直接上报数据，请将<token>替换成从前提条件中获取的Token，将<endpoint>替换成对应地域的Endpoint。

例如：

-javaagent:/Users/carpela/Downloads/opentelemetry-javaagent.jar
-Dotel.resource.attributes=service.name=ot-java-agent-sample
-Dotel.exporter.otlp.headers=Authentication=b590xxxxuqs@3a75d95xxxxx9b_b59xxxxguqs@53dxxxx2afe8301
-Dotel.exporter.otlp.endpoint=http://tracing-analysis-dc-bj:8090

如果您选择使用OpenTelemetry Collector转发，则需删除-Dotel.exporter.otlp.headers=Authentication=<token>并修改<endpoint>为您本地部署的服务地址。

启动应用。
登录ARMS控制台后，在应用监控 > 应用列表页面选择目标应用，查看链路数据。
说明
语言列显示图标的应用为接入应用监控的应用，显示-图标的应用为接入可观测链路 OpenTelemetry 版的应用。