OpenTelemetry を使用して Java アプリケーションデータを報告する - Cloud Monitor

OpenTelemetry でアプリケーションをイベントトラッキングし、そのトレースデータを Cloud Monitor 2.0 に報告すると、Cloud Monitor 2.0 はアプリケーションの監視を開始します。アプリケーショントポロジー、呼び出しトレース、異常なトランザクション、遅いトランザクション、SQL 分析など、さまざまなモニタリングデータを表示できます。このトピックでは、OpenTelemetry Java Agent またはソフトウェア開発キット (SDK) を使用して、自動または手動でイベントトラッキングとデータ報告を行う方法について説明します。

背景情報

OpenTelemetry Java Agent は、多くの Java フレームワークの自動イベントトラッキングをサポートしています。完全なリストについては、「サポートされているライブラリとバージョン」をご参照ください。

サポートされている Java フレームワークを展開して表示

フレームワーク	フレームワークのバージョン要件
Akka Actors	2.5+
Akka HTTP	10.0+
Apache Axis2	1.6+
Apache Camel	2.20+ (3.x はサポートされていません)
Apache DBCP	2.0+
Apache CXF JAX-RS	3.2+
Apache CXF JAX-WS	3.0+
Apache Dubbo	2.7+
Apache HttpAsyncClient	4.1+
Apache HttpClient	2.0+
Apache Kafka Producer/Consumer API	0.11+
Apache Kafka Streams API	0.11+
Apache MyFaces	1.2+ (3.x はサポートされていません)
Apache Pulsar	2.8+
Apache RocketMQ gRPC/Protobuf ベースのクライアント	5.0+
Apache RocketMQ Remoting ベースのクライアント	4.8+
Apache Struts 2	2.3+
Apache Tapestry	5.4+
Apache Wicket	8.0+
Armeria	1.3+
AsyncHttpClient	1.9+
AWS Lambda	1.0+
AWS SDK	1.11.x および 2.2+
Azure Core	1.14+
Cassandra Driver	3.0+
Couchbase Client	2.0+ および 3.1+
c3p0	0.9.2+
Dropwizard Metrics	4.0+ (デフォルトでは無効)
Dropwizard Views	0.7+
Eclipse Grizzly	2.3+
Eclipse Jersey	2.0+ (3.x はサポートされていません)
Eclipse Jetty HTTP Client	9.2+ (10+ はサポートされていません)
Eclipse Metro	2.2+
Eclipse Mojarra	1.2+ (3.x はサポートされていません)
Elasticsearch API Client	7.16+ および 8.0+
Elasticsearch REST Client	5.0+
Elasticsearch Transport Client	5.0+
Finatra	2.9+
Geode Client	1.4+
Google HTTP Client	1.19+
Grails	3.0+
GraphQL Java	12.0+
gRPC	1.6+
Guava ListenableFuture	10.0+
GWT	2.0+
Hibernate	3.3+
Hibernate Reactive	1.0+
HikariCP	3.0+
HttpURLConnection	Java 8+
Hystrix	1.4+
Java Executor	Java 8+
Java Http Client	Java 11+
java.util.logging	Java 8+
Java Platform	Java 8+
JAX-RS	0.5+
JAX-RS Client	1.1+
JAX-WS	2.0+ (3.x を除く)
JBoss Log Manager	1.1+
JDBC	Java 8+
Jedis	1.4+
JMS	1.1+
Jodd Http	4.2+
JSP	2.3+
Kotlin Coroutines	1.0+
Ktor	1.0+
Kubernetes Client	7.0+
Lettuce	4.0+
Log4j 1	1.2+
Log4j 2	2.11+
Logback	1.0+
Micrometer	1.5+
MongoDB Driver	3.1+
Netty	3.8+
OkHttp	2.2+
Oracle UCP	11.2+
OSHI	5.3.1+
Play	2.4+
Play WS	1.0+
Quartz	2.0+
R2DBC	1.0+
RabbitMQ Client	2.7+
Ratpack	1.4+
Reactor	3.1+
Reactor Netty	0.9+
Rediscala	1.8+
Redisson	3.0+
RESTEasy	3.0+
Restlet	1.0+
RMI	Java 8+
RxJava	1.0+
Scala ForkJoinPool	2.8+
Servlet	2.2+
Spark Web Framework	2.3+
Spring Boot	-
Spring Batch	3.0+ (5.0+ はサポートされていません)
Spring Cloud Gateway	2.0+
Spring Data	1.8+
Spring Integration	4.1+ (6.0+ はサポートされていません)
Spring JMS	2.0+
Spring Kafka	2.7+
Spring RabbitMQ	1.0+
Spring Scheduling	3.1+
Spring RestTemplate	3.1+
Spring Web MVC	3.1+
Spring Web Services	2.0+
Spring WebFlux	5.3+
Spymemcached	2.12+
Tomcat JDBC Pool	8.5+
Twilio	6.6+ (8.x はサポートされていません)
Undertow	1.4+
Vaadin	14.2+
Vert.x Web	3.0+
Vert.x HttpClient	3.0+
Vert.x Kafka Client	3.6+
Vert.x RxJava2	3.5+
Vert.x SQL Client	4.0+
Vibur DBCP	11.0+
ZIO	2.0+

ステップ 1: エンドポイント情報を取得する

Cloud Monitor 2.0 コンソールにログインし、ワークスペースを選択します。左側のナビゲーションウィンドウで、[統合センター] をクリックします。
[サーバーサイドアプリケーション] セクションで、[Java] カードをクリックします。次に、[ランタイム環境タイプ] を [手動インストール] に、[プロトコルタイプ] を [Opentelemetry] に設定します。
[パラメーター構成] セクションで、[LicenseKey] の横にある [取得] をクリックします。次に、必要に応じて [イベントトラッキング方法]、[接続方法]、[報告方法] を選択します。[アプリケーション名]、[バージョン番号]、[デプロイメント環境] を入力します。
構成されたパラメーターに基づいて、対応する統合コードがページの下部に生成されます。コードには、Endpoint や LicenseKey などのエンドポイント情報が含まれています。

ステップ 2: 依存関係ライブラリをセットアップする

自動イベントトラッキング (推奨)

OpenTelemetry Java Agent は、非侵入型の統合方法を提供します。数百の Java フレームワークの自動トレースデータ報告をサポートしています。サポートされている Java フレームワークの完全なリストについては、「サポートされているライブラリとバージョン」をご参照ください。

Java Agent をダウンロードします。最新バージョンを推奨します。
Java 起動の VM パラメーターを変更して、トレースデータを報告します。
次のコードは、アプリケーションを実行し、OpenTelemetry Java Agent をロードします。次のコードのプレースホルダーを、ステップ 1 で取得したエンドポイント情報に置き換えます。/path/to/opentelemetry-javaagent.jar と /path/to/your/app.jar を、Java Agent と JAR パッケージへの実際のパスに置き換えます。
```
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=<service name>,acs.cms.workspace=<workspace>,service.version=<service version>,deployment.environment=<environment> \
-Dotel.exporter.otlp.protocol=http/protobuf \
-Dotel.exporter.otlp.traces.endpoint=<traces.endpoint> \
-Dotel.exporter.otlp.metrics.endpoint=<metrics.endpoint> \
-Dotel.exporter.otlp.headers="x-arms-license-key=<license-key>,x-arms-project=<arms-project>,x-cms-workspace=<workspace>" \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jar
```
説明
テストデータを生成するには、サービスにアクセスします。テスト JAR パッケージを使用している場合は、ローカルマシンのポート 8087 にアクセスしてテストデータを生成できます。
プログラムを実行して、トレースデータを生成および報告します。

手動イベントトラッキング

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

OpenTelemetry Tracer を取得します。

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, "<service name>",  // アプリケーション名。
                        ResourceAttributes.SERVICE_VERSION, "<service version>",  // バージョン番号。
                        ResourceAttributes.DEPLOYMENT_ENVIRONMENT, "<environment>", // デプロイメント環境。
                        ResourceAttributes.HOST_NAME, "${host-name}", // ${host-name} をホスト名に置き換えます。
                        AttributeKey.stringKey("acs.cms.workspace"), "<workspace>"  // <workspace> をワークスペース名に置き換えます。
                )));
        
        SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
                .addSpanProcessor(BatchSpanProcessor.builder(OtlpHttpSpanExporter.builder()
                        .setEndpoint("<endpoint>")  // <endpoint> をステップ 1 で取得したエンドポイント情報に置き換えます。
                        .addHeader("x-arms-license-key", "<license-key>")  // <license-key> をステップ 1 で取得した情報に置き換えます。
                        .addHeader("x-arms-project", "<arms-project>")  // <arms-project> をステップ 1 で取得した情報に置き換えます。
                        .addHeader("x-cms-workspace", "<workspace>") // <workspace> をワークスペース名に置き換えます。
                        .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;
    }
}

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 をダウンロードします。最新バージョンを推奨します。

手動イベントトラッキングの 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 依存関係を展開して表示

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

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 のコードです。コードに示されている最初の方法と 2 番目の方法が推奨されます。

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

        // 方法 1: 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";
        }

        // 方法 2: アノテーションを使用してイベントトラッキングを作成する。
        @WithSpan
        private void child(@SpanAttribute("user.type") String userType) {
            System.out.println(userType);
            biz();
        }

        // 方法 3: 純粋な手動イベントトラッキングのために 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); // いくつかの非同期ジョブ
                        } catch (Throwable e) {
                        }
                        asyncSpan.end();
                    }
                });

                Thread.sleep(1000); // 偽のビジネスロジック
                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 パラメーターを変更して、トレースデータを報告します。

次のコードのプレースホルダーを、ステップ 1 で取得したエンドポイント情報に置き換えます。/path/to/opentelemetry-javaagent.jar と /path/to/your/app.jar を、Java Agent と JAR パッケージへの実際のパスに置き換えます。

java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.resource.attributes=service.name=<service name>,acs.cms.workspace=<workspace>,service.version=<service version>,deployment.environment=<environment> \
-Dotel.exporter.otlp.protocol=http/protobuf \
-Dotel.exporter.otlp.traces.endpoint=<traces.endpoint> \
-Dotel.exporter.otlp.metrics.endpoint=<metrics.endpoint> \
-Dotel.exporter.otlp.headers="x-arms-license-key=<license-key>,x-arms-project=<arms-project>,x-cms-workspace=<workspace>" \
-Dotel.logs.exporter=none \
-jar /path/to/your/app.jar

プログラムを実行して、トレースデータを生成および報告します。

モニタリングデータを表示する

Cloud Monitor 2.0 コンソールにログインし、ワークスペースを選択します。左側のナビゲーションウィンドウで、[アプリケーションセンター] > [アプリケーションオブザーバビリティ] > [アプリケーション監視] を選択します。
[アプリケーションリスト] ページで、アプリケーションの名前をクリックして、その監視詳細を表示します。詳細については、「アプリケーション監視」をご参照ください。