通過OpenTelemetry為應用埋點並上報鏈路資料至Managed Service for OpenTelemetry後，Managed Service for 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參數上報鏈路資料。
-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的埋點不滿足您的情境或者需要增加一些自訂業務埋點時，可以使用以下方式接入。
引入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 版的應用。