Application Real-Time Monitoring Service:Use OpenTelemetry to report the trace data of Java applications

Background information

The following table describes the Java frameworks that the OpenTelemetry Java agent can automatically instrument. For more information, see Supported libraries, frameworks, application servers, and JVMs.

Sample code

Download the sample code from java-opentelemetry-demo.

Method 1: Use the OpenTelemetry Java agent to automatically instrument an application

The OpenTelemetry Java agent allows you to connect OpenTelemetry to Managed Service for OpenTelemetry in a non-intrusive manner. The OpenTelemetry Java agent can be used to automatically upload trace data in hundreds of Java frameworks. For more information about the supported Java frameworks, see Supported libraries, frameworks, application servers, and JVMs.

1. Download the OpenTelemetry Java agent.

2. Modify the JVM parameters in the Java startup configuration to report trace data.

   • Through HTTP: Set the trace and metric endpoints.

   • Through gRPC: Set the trace endpoint and authentication token.

   HTTP

   java -javaagent:/path/to/opentelemetry-javaagent.jar\   # Specify the file download path.
   -Dotel.resource.attributes=service.name=,service.version=,deployment.environment= \
   -Dotel.exporter.otlp.protocol=http/protobuf \
   -Dotel.exporter.otlp.traces.endpoint=<traces.endpoint> \   # Specify the trace endpoint you obtained in the Prerequisites section.
   -Dotel.exporter.otlp.metrics.endpoint=<metrics.endpoint> \   # Specify the metric endpoint you obtained in the Prerequisites section.
   -Dotel.logs.exporter=none \
   -jar /path/to/your/app.jar  # Specify the path for storing your JAR package.

   Example:

   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 \   # Specify the file download path.
   -Dotel.resource.attributes=service.name=,service.version=,deployment.environment= \
   -Dotel.exporter.otlp.protocol=grpc \
   -Dotel.exporter.otlp.headers=Authentication=<token> \   # Specify the authentication token you obtained in the Prerequisites section.
   -Dotel.exporter.otlp.endpoint=<endpoint> \   # Specify the endpoint you obtained in the Prerequisites section.
   -Dotel.logs.exporter=none \
   -jar /path/to/your/app.jar     # Specify the path for storing your JAR package.

   Example:

   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

   Note

   If you want to use the OpenTelemetry Collector to forward trace data, remove -Dotel.exporter.otlp.headers=Authentication=<token> and replace <endpoint> with the URL of the service that is deployed on an on-premises machine.

Method 2: Use OpenTelemetry SDK for Java to manually instrument an application

The OpenTelemetry Java agent is implemented based on OpenTelemetry SDK for Java. The SDK provides various custom features. If the instrumentation that is added by using the OpenTelemetry Java agent no longer meets your business requirements or you want to add custom instrumentation based on your business requirements, perform the following steps:

1. Add the following dependencies to the pom.xml file of a Maven project:

   <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. Obtain an 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 {
           // Obtain an OpenTelemetry tracer.
           Resource resource = Resource.getDefault()
                   .merge(Resource.create(Attributes.of(
                           ResourceAttributes.SERVICE_NAME, "",  // The application name.
                           ResourceAttributes.SERVICE_VERSION, "",  // The version number.
                           ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "", // The environment.
                           ResourceAttributes.HOST_NAME, "${host-name}" // Change ${host-name} to your server name.
                   )));
           
           SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
                   .addSpanProcessor(BatchSpanProcessor.builder(OtlpHttpSpanExporter.builder()
                           .setEndpoint("<endpoint>")  // Change <endpoint> to the endpoint you obtained in the Prerequisites section.
                           .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 {
           // Obtain an OpenTelemetry tracer.
           Resource resource = Resource.getDefault()
                   .merge(Resource.create(Attributes.of(
                           ResourceAttributes.SERVICE_NAME, "", // The application name.
                           ResourceAttributes.SERVICE_VERSION, "", // The version number.
                           ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "", // The environment.
                           ResourceAttributes.HOST_NAME, "${host-name}" // Change ${host-name} to your server name.
                   )));
           
           SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
                   .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder()
                           .setEndpoint("<endpoint>") // Change <endpoint> to the endpoint you obtained in the Prerequisites section.
                           .addHeader("Authentication", "<token>") // Change <token> to the authentication token you obtained in the Prerequisites section.
                           .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. Create a 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();
       }
   }

4. Start the application.

   Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Applications. On the Applications page, click the name of the application. On the page that appears, view the trace data.

   Note

   If the icon is displayed in the Language column, the application is connected to Application Monitoring. If a hyphen (-) is displayed, the application is connected to Managed Service for OpenTelemetry.

Method 3: Use the OpenTelemetry Java agent and OpenTelemetry SDK for Java to instrument applications

You can use the OpenTelemetry Java agent to perform automatic instrumentation and use OpenTelemetry SDK for Java to add custom instrumentation based on your business requirements.

1. Download the OpenTelemetry Java agent.

2. Add the following dependencies to the pom.xml file of the Maven project in addition to the dependencies of Method 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>

   Note

   In the preceding code, the opentelemetry-sdk-extension-autoconfigure dependency is used to automatically configure OpenTelemetry SDK for Java and transfer the settings of the OpenTelemetry Java agent to the SDK.

   View the dependencies in the pom.xml file of the Maven project

   <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. Obtain an OpenTelemetry Tracer.

   If you use the OpenTelemetry Java agent and OpenTelemetry SDK for Java to instrument applications, you do not need to use the OpenTelemetrySupport class used in Method 2 to obtain an OpenTelemetry tracer.

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

4. Modify the controller code and service code.

   • We recommend that you use Method 1 and Method 2 in the following sample controller code:

     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;
     
     /**
     * References:
     * 1. https://opentelemetry.io/docs/java/manual_instrumentation/
     */
     @RestController
         @RequestMapping("/user")
         public class UserController {
     
             @Autowired
             private UserService userService;
     
             private ExecutorService es = Executors.newFixedThreadPool(5);
     
             // Method 1: Perform automatic instrumentation on an application. Call an API operation to add information.
             @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";
             }
     
             // Method 2: Instrument an application based on tags.
             @WithSpan
             private void child(@SpanAttribute("user.type") String userType) {
                 System.out.println(userType);
                 biz();
             }
     
             // Method 3: Use a tracer to manually instrument an application.
             private void biz() {
                 Tracer tracer = GlobalOpenTelemetry.get().getTracer("tracer");
                 Span span = tracer.spanBuilder("biz (manual)")
                     .setParent(Context.current().with(Span.current())) // Optional. The system automatically configures the settings.
                     .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();
                 }
             }
     
         }
     
                                     

   • Sample service code:

     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. Modify the JVM parameters in the Java startup configuration to report trace data.

   -javaagent:/path/to/opentelemetry-javaagent.jar    // Replace the path with the URL that you use to download the OpenTelemetry Java agent. 
   -Dotel.resource.attributes=service.name=<appName>     // Replace <appName> with an actual application name. 
   -Dotel.exporter.otlp.headers=Authentication=<token>
   -Dotel.exporter.otlp.endpoint=<endpoint>

   • If you want to directly report trace data, replace <token> with the token that you obtained in the prerequisites and <endpoint> with the endpoint of the region to which you want to report the trace data.

     Example:

     -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

   • If you want to use the OpenTelemetry Collector to forward trace data, remove -Dotel.exporter.otlp.headers=Authentication=<token> and replace <endpoint> with the URL of the service that is deployed on an on-premises machine.

6. Start the application.

   Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Applications. On the Applications page, click the name of the application. On the page that appears, view the trace data.

   Note

   If the icon is displayed in the Language column, the application is connected to Application Monitoring. If a hyphen (-) is displayed, the application is connected to Managed Service for OpenTelemetry.