通过OpenTelemetry为应用埋点并上报链路数据至可观测链路 OpenTelemetry 版后，可观测链路 OpenTelemetry 版即可开始监控应用，您可以查看应用拓扑、调用链路、异常事务、慢事务和SQL分析等一系列监控数据。本文介绍如何使用OpenTelemetry Java Agent/SDK进行自动或手动埋点并上报数据。
前提条件
登录ARMS控制台，在左侧导航栏单击接入中心。
在服务端应用区域单击OpenTelemetry卡片。
在弹出的OpenTelemetry面板中选择数据需要上报的地域。
说明初次接入的地域将会自动进行资源初始化。
选择连接方式和上报方式，然后复制接入点信息。
连接方式：若您的服务部署在阿里云上，且所属地域与选择的接入地域一致，推荐使用阿里云内网方式，否则选择公网方式。
上报方式：根据客户端支持的协议类型选择HTTP或gRPC协议上报数据。
背景信息
OpenTelemetry Java Agent支持自动埋点的Java框架列表如下，完整信息请参考Supported Libraries and Versions。
示例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.jargRPC方式
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中。获取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 版的应用。