Managed Service for OpenTelemetry：Gunakan OpenTelemetry untuk melaporkan data jejak aplikasi Java

Informasi latar belakang

Tabel berikut mencantumkan kerangka kerja Java yang dapat diinstrumentasi secara otomatis oleh agen Java OpenTelemetry. Untuk informasi lebih lanjut, lihat Perpustakaan, kerangka kerja, server aplikasi, dan JVM yang didukung.

Kode contoh

Unduh kode contoh dari java-opentelemetry-demo.

Metode 1: Gunakan agen Java OpenTelemetry untuk menginstrumentasi aplikasi secara otomatis

Agen Java OpenTelemetry memungkinkan Anda menghubungkan OpenTelemetry ke Managed Service for OpenTelemetry secara non-intrusif. Agen ini mendukung pengunggahan data jejak secara otomatis di ratusan kerangka kerja Java. Untuk daftar kerangka kerja Java yang didukung, lihat Perpustakaan, kerangka kerja, server aplikasi, dan JVM yang didukung.

1. Unduh agen Java OpenTelemetry.

2. Ubah parameter JVM dalam konfigurasi startup Java untuk melaporkan data jejak.

   • Melalui HTTP: Atur titik akhir jejak dan metrik.

   • Melalui gRPC: Atur titik akhir jejak dan token otentikasi.

   HTTP

   java -javaagent:/path/to/opentelemetry-javaagent.jar\   # Tentukan jalur unduhan file.
   -Dotel.resource.attributes=service.name=,service.version=,deployment.environment= \
   -Dotel.exporter.otlp.protocol=http/protobuf \
   -Dotel.exporter.otlp.traces.endpoint=<traces.endpoint> \   # Tentukan titik akhir jejak yang Anda peroleh di bagian Prasyarat.
   -Dotel.exporter.otlp.metrics.endpoint=<metrics.endpoint> \   # Tentukan titik akhir metrik yang Anda peroleh di bagian Prasyarat.
   -Dotel.logs.exporter=none \
   -jar /path/to/your/app.jar  # Tentukan jalur penyimpanan paket JAR Anda.

   Contoh:

   java -javaagent:/path/to/opentelemetry-javaagent.jar \
   -Dotel.resource.attributes=service.name=,service.version=,deployment.environment= \
   -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 \   # Tentukan jalur unduhan file.
   -Dotel.resource.attributes=service.name=,service.version=,deployment.environment= \
   -Dotel.exporter.otlp.protocol=grpc \
   -Dotel.exporter.otlp.headers=Authentication=<token> \   # Tentukan token otentikasi yang Anda peroleh di bagian Prasyarat.
   -Dotel.exporter.otlp.endpoint=<endpoint> \   # Tentukan titik akhir yang Anda peroleh di bagian Prasyarat.
   -Dotel.logs.exporter=none \
   -jar /path/to/your/app.jar     # Tentukan jalur penyimpanan paket JAR Anda.

   Contoh:

   java -javaagent:/path/to/opentelemetry-javaagent.jar \
   -Dotel.resource.attributes=service.name=,service.version=,deployment.environment= \
   -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

   Catatan

   Jika Anda ingin menggunakan OpenTelemetry Collector untuk meneruskan data jejak, hapus -Dotel.exporter.otlp.headers=Authentication=<token> dan ganti <endpoint> dengan URL layanan yang diterapkan pada mesin lokal.

Metode 2: Gunakan OpenTelemetry SDK untuk Java untuk menginstrumentasi aplikasi secara manual

Agen Java OpenTelemetry diimplementasikan berdasarkan OpenTelemetry SDK untuk Java. SDK ini menyediakan berbagai fitur kustomisasi. Jika instrumentasi yang ditambahkan menggunakan agen Java OpenTelemetry tidak lagi memenuhi kebutuhan bisnis Anda atau Anda ingin menambahkan instrumentasi kustom, ikuti langkah-langkah berikut:

1. Tambahkan dependensi berikut ke file pom.xml proyek Maven:

   <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. Dapatkan tracer OpenTelemetry.

   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 {
           // Dapatkan tracer OpenTelemetry.
           Resource resource = Resource.getDefault()
                   .merge(Resource.create(Attributes.of(
                           ResourceAttributes.SERVICE_NAME, "",  // Nama aplikasi.
                           ResourceAttributes.SERVICE_VERSION, "",  // Nomor versi.
                           ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "", // Lingkungan.
                           ResourceAttributes.HOST_NAME, "${host-name}" // Ganti ${host-name} dengan nama server Anda.
                   )));
           
           SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
                   .addSpanProcessor(BatchSpanProcessor.builder(OtlpHttpSpanExporter.builder()
                           .setEndpoint("<endpoint>")  // Ganti <endpoint> dengan titik akhir yang Anda peroleh di bagian Prasyarat.
                           .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;
       }
   }

   gRPC

   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 {
           // Dapatkan tracer OpenTelemetry.
           Resource resource = Resource.getDefault()
                   .merge(Resource.create(Attributes.of(
                           ResourceAttributes.SERVICE_NAME, "", // Nama aplikasi.
                           ResourceAttributes.SERVICE_VERSION, "", // Nomor versi.
                           ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "", // Lingkungan.
                           ResourceAttributes.HOST_NAME, "${host-name}" // Ganti ${host-name} dengan nama server Anda.
                   )));
           
           SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
                   .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
                           .setEndpoint("<endpoint>") // Ganti <endpoint> dengan titik akhir yang Anda peroleh di bagian Prasyarat.
                           .addHeader("Authentication", "<token>") // Ganti <token> dengan token otentikasi yang Anda peroleh di bagian Prasyarat.
                           .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. Buat rentang.

   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();
       }
   }

4. Mulai aplikasi.

   Di halaman Applications dari Konsol Managed Service for OpenTelemetry, klik nama aplikasi. Di halaman yang muncul, lihat data jejak.

Metode 3: Gunakan agen Java OpenTelemetry dan OpenTelemetry SDK untuk Java untuk menginstrumentasi aplikasi

Anda dapat menggunakan agen Java OpenTelemetry untuk melakukan instrumentasi otomatis dan OpenTelemetry SDK untuk Java untuk menambahkan instrumentasi kustom sesuai kebutuhan bisnis Anda.

1. Unduh agen Java OpenTelemetry.

2. Tambahkan dependensi berikut ke file pom.xml proyek Maven selain dependensi dari Metode 2:

   <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>

   Catatan

   Pada kode sebelumnya, dependensi opentelemetry-sdk-extension-autoconfigure digunakan untuk mengonfigurasi OpenTelemetry SDK untuk Java secara otomatis dan mentransfer pengaturan agen Java OpenTelemetry ke SDK.

   Lihat dependensi dalam file pom.xml proyek Maven

   <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.30.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.30.0</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>

3. Dapatkan Tracer OpenTelemetry.

   Jika Anda menggunakan agen Java OpenTelemetry dan OpenTelemetry SDK untuk Java untuk menginstrumentasi aplikasi, Anda tidak perlu menggunakan kelas OpenTelemetrySupport yang digunakan di Metode 2 untuk mendapatkan tracer OpenTelemetry.

   OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
   Tracer tracer = openTelemetry.getTracer("instrumentation-library-name", "1.0.0");

4. Ubah kode controller dan kode layanan.

   • Kami sarankan Anda menggunakan Metode 1 dan Metode 2 dalam kode controller sampel berikut:

     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.api.trace.propagation.W3CTraceContextPropagator;
     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;
     
     /**
     * Referensi:
     * 1. https://opentelemetry.io/docs/java/manual_instrumentation/
     */
     @RestController
         @RequestMapping("/user")
         public class UserController {
     
             @Autowired
             private UserService userService;
     
             private ExecutorService es = Executors.newFixedThreadPool(5);
     
             // Metode 1: Lakukan instrumentasi otomatis pada aplikasi. Panggil operasi API untuk menambahkan informasi.
             @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";
             }
     
             // Metode 2: Instrumentasi aplikasi berdasarkan tag.
             @WithSpan
             private void child(@SpanAttribute("user.type") String userType) {
                 System.out.println(userType);
                 biz();
             }
     
             // Metode 3: Gunakan tracer untuk menginstrumentasi aplikasi secara manual.
             private void biz() {
                 Tracer tracer = GlobalOpenTelemetry.get().getTracer("tracer");
                 Span span = tracer.spanBuilder("biz (manual)")
                     .setParent(Context.current().with(Span.current())) // Opsional. Sistem secara otomatis mengonfigurasi pengaturan.
                     .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); // beberapa pekerjaan asinkron
                             } catch (Throwable e) {
                             }
                             asyncSpan.end();
                         }
                     });
     
                     Thread.sleep(1000); // logika bisnis palsu
                     System.out.println("biz done");
                     OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
                     openTelemetry.getPropagators();
                 } catch (Throwable t) {
                     span.setStatus(StatusCode.ERROR, "handle biz error");
                 } finally {
                     span.end();
                 }
             }
     
         }
     
                                     

   • Kode layanan contoh:

     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. Ubah parameter JVM dalam konfigurasi startup Java untuk melaporkan data jejak.

   -javaagent:/path/to/opentelemetry-javaagent.jar    // Ganti jalur dengan URL yang Anda gunakan untuk mengunduh agen Java OpenTelemetry. 
   -Dotel.resource.attributes=service.name=<appName>     // Ganti <appName> dengan nama aplikasi aktual. 
   -Dotel.exporter.otlp.headers=Authentication=<token>
   -Dotel.exporter.otlp.endpoint=<endpoint>

   • Jika Anda ingin langsung melaporkan data jejak, ganti <token> dengan token yang Anda peroleh di prasyarat dan <endpoint> dengan titik akhir wilayah tempat Anda ingin melaporkan data jejak.

     Contoh:

     -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

   • Jika Anda ingin menggunakan OpenTelemetry Collector untuk meneruskan data jejak, hapus -Dotel.exporter.otlp.headers=Authentication=<token> dan ganti <endpoint> dengan URL layanan yang diterapkan pada mesin lokal.

6. Mulai aplikasi.

   Di halaman Applications dari Konsol Managed Service for OpenTelemetry, klik nama aplikasi. Di halaman yang muncul, lihat data jejak.