OpenTelemetry学习笔记(一)：示例demo，通过OpenTelemetry上报Java应用数据的三种方式

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

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

这里我们将使用一个名为 Petclinic 的 Java 应用程序，这是一个使用 Maven 或 Gradle 构建的 Spring Boot 应用程序。该应用程序将使用 OpenTelemetry 生成数据。

对于 Java 应用，我们可以通过下载 OpenTelemetry 提供的 opentelemetry-javaagent 这个 jar 包来使用 OpenTelemetry 自动检测应用程序。

只需要将这个 jar 包添加到应用程序的启动命令中即可，比如：

java -javaagent:opentelemetry-javaagent.jar -jar target/*.jar

方法二：使用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.30.0-alpha</version>
       </dependency>
   </dependencies>
   
   <dependencyManagement>
   <dependencies>
       <dependency>
           <groupId>io.opentelemetry</groupId>
           <artifactId>opentelemetry-bom</artifactId>
           <version>1.30.0</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
   </dependencies>
   </dependencyManagement>

2. 获取OpenTelemetry Tracer。

   HTTP方式

   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.http.trace.OtlpHttpSpanExporter;
   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, "",  // 应用名。
                           ResourceAttributes.SERVICE_VERSION, "",  // 版本号。
                           ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "", // 部署环境。
                           ResourceAttributes.HOST_NAME, "${host-name}" // 请将 ${host-name} 替换为您的主机名。
                   )));
           
           SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
                   .addSpanProcessor(BatchSpanProcessor.builder(OtlpHttpSpanExporter.builder()
                           .setEndpoint("<endpoint>")  // 请将<endpoint>替换为前提条件中获取的接入点信息。
                           .build()).build())
                   .setResource(resource)
                   .build();
           
           OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
                   .setTracerProvider(sdkTracerProvider)
                   .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
                   .buildAndRegisterGlobal();
   
           tracer = openTelemetry.getTracer("OpenTelemetry Tracer", "1.0.0");
       }
   
       private static Tracer tracer;
   
       public static Tracer getTracer() {
           return tracer;
       }
   }

3. 创建 Span。

   import io.opentelemetry.api.trace.Span;
   import io.opentelemetry.api.trace.StatusCode;
   import io.opentelemetry.context.Scope;
   
   public class Main {
       
       public static void parentMethod() {
           Span span = OpenTelemetrySupport.getTracer().spanBuilder("parent span").startSpan();
           try (Scope scope = span.makeCurrent()) {
               span.setAttribute("good", "job");
               childMethod();
           } catch (Throwable t) {
               span.setStatus(StatusCode.ERROR, "handle parent span error");
           } finally {
               span.end();
           }
       }
   
       public static void childMethod() {
           Span span = OpenTelemetrySupport.getTracer().spanBuilder("child span").startSpan();
           try (Scope scope = span.makeCurrent()) {
               span.setAttribute("hello", "world");
           } catch (Throwable t) {
               span.setStatus(StatusCode.ERROR, "handle child span error");
           } finally {
               span.end();
           }
       }
   
       public static void main(String[] args) {
           parentMethod();
       }
   }

方法三：同时使用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依赖

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>为您本地部署的服务地址。