文档

通过OpenTelemetry上报Java应用数据

更新时间:

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

前提条件

获取接入点信息

  1. 登录可观测链路 OpenTelemetry 版控制台

  2. 在左侧导航栏单击集群配置,然后在右侧页面单击接入点信息页签。

  3. 在页面顶部选择需要接入的地域,然后在集群信息区域打开显示Token开关。

  4. 客户端采集工具区域单击OpenTelemetry

    在下方表格的相关信息列中,获取接入点信息。OT接入点信息

    说明

    如果应用部署于阿里云生产环境,则选择阿里云VPC网络接入点,否则选择公网接入点。

背景信息

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

  1. 下载Java Agent

  2. 通过修改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>
    -Dotel.metrics.exporter=none
    • 如果您选择直接上报数据,请将<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
      -Dotel.metrics.exporter=none
    • 如果您选择使用OpenTelemetry Collector转发,则需删除-Dotel.exporter.otlp.headers=Authentication=<token>并修改<endpoint>为您本地部署的服务地址。

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

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

  1. 引入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>
  2. 获取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;
        }
    
    }
  3. 参考以下内容修改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 -- ");
          }
      }
  4. 启动应用。

    可观测链路 OpenTelemetry 版控制台应用列表页面选择目标应用,查看链路数据。

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

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

  1. 下载Java Agent

  2. 方法二的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>com.alibaba.arms</groupId>
            <artifactId>brightroar-dao</artifactId>
            <version>0.0.1-SNAPSHOT</version>
        </dependency>
        <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>
  3. 获取OpenTelemetry Tracer。

    同时使用Java Agent和Java SDK埋点时,无需再使用方法二中的OpenTelemetrySupport类获取Tracer。

    OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
    Tracer tracer = openTelemetry.getTracer("instrumentation-library-name", "1.0.0");
  4. 参考以下内容修改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 -- ");
          }
      }
  5. 通过修改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>为您本地部署的服务地址。

  6. 启动应用。

    可观测链路 OpenTelemetry 版控制台应用列表页面选择目标应用,查看链路数据。

  • 本页导读 (1)