OpenTelemetry(ADOT)による自動計装

OpenTelemetryを使ったJava, Python, Node.js(JavaScript), Goの自動計装方法についての資料です。
お役に立てれば幸いです。

Transcript

1. OpenTelemetry（ADOT）による 自動計装 2025/11/6 李俊起
2. 話す内容 2025/11/6 2 • OpenTelemetryについて • 計装について • 手動計装 • 自動計装 • 各言語の自動計装 ➢ Java ➢ Python ➢ Node.js（JavaScript） ➢ Go NOTE！ 本ドキュメントは、基本的に ADOT、OTLP/HTTPの利用と、ECS(Fargate)構成を前提としています。
3. 2025/11/6 3 OpenTelemetryについて
4. OpenTelemetryとは 2025/11/6 4 • テレメトリーデータ(Trace, Metric, Log)収集/連携のために 以下を提供 ➢ SDK/API ➢ OpenTelemetry Collector ➢ OTLP ➢ etc. • OpenTelemetry自体はバックエンドを持たない ➢ データフォーマット、データ収集、連携の部分のみを担当 • ベンダーに依存しない（ベンダーニュートラル）
5. OTLP（OpenTelemetry Protocol） 2025/11/6 5 • すべてのシグナル(Trace, Metric, Log)のための、 アプリケーション、エージェント、バックエンド間のデータ送信を行う ためのプロトコル • ベースプロトコルとして、 gRPC over HTTP/2 （otlp/grpc）と HTTP（otlp/http）の 両方をサポート • 主要なObservabilityツールやベンダーはOTLPに対応している
6. OpenTelemetry Collector 1/2 2025/11/6 6 • 以下を行うエージェント テレメトリーデータ(Trace, Metric, Log)を 、 ①（様々なフォーマットのデータを）受信して ② バッチ/前処理して ③（データを様々なフォーマットに変換して）バックエンドに送信する • 以下のコンポーネントから構成されている ① Receiver : 様々なフォーマットでデータを受信する ② Processor : Exporterに流す前に処理をする（e.g. batch処理、Ａｔｔｒｉｂｕｔeの追 加） ③ Exporter : データをバックエンド(e.g. o11yツール)に送信する
7. OpenTelemetry Collector 2/2 2025/11/6 7 Receiver Processor Exporter New Relic X-Ray Cloud Watch Cloud Watch Logs OpenTelemetry Collector otlp awsxray awsemf fluentforward otlp prometheus OpenTelemetry Java agent exporter ・ ・ ・ Fluentd otlp prometheusremotewrite Tempo Loki １つのデータ種類(e.g. ログ)を 複数のバックエンドに送ることも 可能 Fluent Bit
8. ADOT（AWS Distro for OpenTelemetry） 2025/11/6 8 • 標準のOpenTelemetryに、 AWSに合わせた様々な機能が追加されたディストリビューション • ADOTを使う理由（メリット） ➢ AWSサービスとの連携のための設定が予め組み込まれている ➢ 例えば、ADOT Collectorには、X-RayやCloudWatchなど、AWSサービスと の連携のためのコンポーネントが事前にビルドされている。 各言語の自動計装用Agentでは、デフォルトでデータの送信先エンドポイントと して、CloudWatch LogsやX-Rayなど、AWSサービスが設定されており、 X-Amzn-Trace-Idヘッダーも伝播するように設定されている。 ➢ AWSからサポートを受けられる
9. ※Context Propagation（コンテキスト伝播） 2025/11/6 9 • Propagationの規格があり、 ＡＷＳは独自の規格で X-Amzn-Trace-Id、 OpenTelemetryはデフォルトでW3C Trace Context • システム間でこの形式が合わないとトレースが途切れることも ① ④ ①～④を繰り返し Application H T T P H T T P OpenTelemetry SDK/ Auto Instrumentation Header ------------- Trace ID: xxx Span ID : xxx ・ ・ Header ------------- Trace ID: xxx Span ID : xxx ・ ・ ② ③ Backend （e.g. Otel Collector、X-Ray） Contextが含まれている ヘッダーが連携される ヘッダーにある Contextを抽出する SDK等によって生成された処理に関するデータと、 Trace ID/Span ID等が含まれる TraceデータをBackendに送る 新たに生成されたContextを ヘッダーに注入する ※Trace IDは不変
10. 2025/11/6 10 計装について
11. 計装（instrumentation）とは 2025/11/6 11 • アプリケーションに関するテレメトリーデータを収集できるように、 コードを修正するなど、何かしら設定をすること • 直接コードを修正する「手動計装」、コードを修正する必要のない 「自動計装（※） 」の２つの方法がある ※「Zero Code計装」ともいうが、ここでは「自動計装」で統一
12. 手動計装 2025/11/6 12 • アプリケーションコードに各言語用のOpenTelemetry API/SDK を使って、直接テレメトリデータ生成のためのコードを追加 • 自動計装ではできない生成するデータの種類・箇所・粒度などの カスタマイズができる
13. 自動計装 2025/11/6 13 • アプリケーションコードを修正することなく、テレメトリーデータを取得 できるようにする仕組み • 各言語ごとに自動計装の仕組みや取得できるデータ種類、 連携方法などが異なる • テレメトリーデータが自動生成されるのは、各言語の Instrumentationライブラリがサポートしている ライブラリ/フレームワークの処理のみ ➢ すべてのデータが自動生成/取得されるわけではない
14. 2025/11/6 14 Javaの自動計装
15. Javaの自動計装 2025/11/6 15 • Java Agentとして、Otel(ADOT)のJava Agentを指定して実行 するだけ • Spring Bootの場合、Actuatorと組み合わせて使うことも可能 • アプリケーションコードの修正は不要だけど、以下の設定ファイルの 修正は必要 ➢ pom.xml（または build.gradle） ➢ logback-spring.xml ➢ application.properties
16. Javaの自動計装（pom.xmlの設定例） 2025/11/6 16 • pom.xmlの<dependencies>に以下を追加 <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-registry-prometheus</artifactId> </dependency> <dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-tracing-bridge-otel</artifactId> </dependency> <dependency> <groupId>io.opentelemetry.instrumentation</groupId> <artifactId>opentelemetry-logback-mdc-1.0</artifactId> <version>2.20.1-alpha</version> </dependency> <dependency> <groupId>software.amazon.opentelemetry</groupId> <artifactId>aws-opentelemetry-agent</artifactId> <version>2.11.5</version> </dependency> </dependencies>
17. Javaの自動計装（logback-spring.xmlの設定例） 2025/11/6 17 • logback-spring.xmlの<dependencies>に以下を追加 ※フォーマット（pattern）は適宜修正 <?xml version="1.0" encoding="UTF-8"?> <configuration> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - trace_id=%X{trace_id} span_id=%X{span_id} trace_flags=%X{trace_flags} - %msg%n</pattern> </encoder> </appender> <appender name="OpenTelemetry" class="io.opentelemetry.instrumentation.logback.mdc.v1_0.OpenTelemetryAppender"> <appender-ref ref="CONSOLE"/> </appender> <root level="INFO"> <appender-ref ref="OpenTelemetry"/> </root> </configuration>
18. Javaの自動計装（application.propertiesの設定例） 2025/11/6 18 • application.propertiesに以下を追加 otel.propagators=tracecontext,baggage management.endpoints.web.exposure.include=health,prometheus management.metrics.export.prometheus.enabled=true management.metrics.distribution.percentiles-histogram.http.server.requests=true management.metrics.distribution.percentiles.http.server.requests=0.5, 0.75, 0.9, 0.95, 0.99 management.metrics.tags.<メトリクスに含める任意のタグ名> =<任意のタグの値> management.metrics.tags.env=dev
19. Javaの自動計装（環境変数の設定・実行） 2025/11/6 19 • 以下のように、環境変数を設定し、 ADOT Java Agent(※) を指定してアプリを実行 ※ 以下から最新バージョンのADOT Java Agentをダウンロード https://github.com/aws-observability/aws-otel-java-instrumentation/releases $ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \ OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \ OTEL_LOGS_EXPORTER=otlp \ OTEL_METRICS_EXEMPLAR_FILTER=trace_based \ OTEL_METRICS_EXPORTER=prometheus \ OTEL_LOGS_EXPORTER=otlp \ OTEL_TRACES_EXPORTER=otlp \ OTEL_SERVICE_NAME=<サービス or システム名> $ java -javaagent:path/to/aws-opentelemetry-agent.jar –jar app.jar
20. Javaの自動計装（全体像） 2025/11/6 20 • Logはfirelens → AWS for Fluent-Bit → Loki、 TraceとMetricはADOT Collector → Tempo/Thanosに転送 ADOT Collector AWS for Fluent Bit Tempo Loki Prometheus Endpoint Trace Metric Log Log Metric Trace
21. ※Exemplarとは 2025/11/6 21 • メトリクスとトレースを結びつける仕組み ➢ メトリクスからトレースへの遷移が可能になる • OpenMetricsの仕様で形式が定まっている • 以下はExemplar付きメトリクスの例で、 「#」以降がExemplarで拡張された部分 http_server_requests_seconds_count{method="POST",status="200"} 5.0 # {span_id="62212b47f709b02c",trace_id="22451e263bfcd9ec6e864c26ab0cebfa"} 1.0 1760358514.383 ※今回ご紹介する４つの言語の中ではJavaが唯一自動計装でExemplarsまで生成してくれる
22. ※ADOT Collectorの設定例 2025/11/6 22 • otlpとprometheusのReceiverから Tempo/Thanos/Lokiへ転送する例 receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 prometheus: config: scrape_configs: - job_name: 'java-otel-metrics' scrape_interval: 30s static_configs: - targets: ['localhost:9464'] labels: source: 'otel-java-agent' - job_name: 'java-actuator-metrics' scrape_interval: 15s metrics_path: '/actuator/prometheus' static_configs: - targets: ['localhost:8081'] labels: source: 'spring-actuator' ・・続き・・ service: pipelines: traces: receivers: [otlp] exporters: [otlphttp/tempo] metrics: receivers: [otlp, prometheus] exporters: [prometheusremotewrite/thanos] logs: receivers: [otlp] exporters: [otlphttp/loki] ※ processorブロックは省略しています。必要に応じ てbatchなど、processorを追加してください。
23. 2025/11/6 23 Pythonの自動計装
24. Pythonの自動計装 2025/11/6 24 • 「aws-opentelemetry-distro」パッケージをインストールし、 以下の環境変数を設定の上、 「opentelemetry-instrument」 を付けて実行するだけ $ pip install aws-opentelemetry-distro $ OTEL_PYTHON_DISTRO=aws_distro \ OTEL_PYTHON_CONFIGURATOR=aws_configurator \ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \ OTEL_TRACES_EXPORTER=otlp \ OTEL_METRICS_EXPORTER=otlp \ OTEL_LOGS_EXPORTER=otlp \ OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \ OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true OTEL_PYTHON_LOG_CORRELATION=true OTEL_PYTHON_LOG_FORMAT=%(asctime)s [%(levelname)s] trace_id=%(otelTraceID)s span_id=%(otelSpanID)s - %(message)s # ログフォーマットは必要に応じて適宜変更 OTEL_SERVICE_NAME=<サービス or システム名> $ opentelemetry-instrument python3 ./path/to/your/app.py
25. Pythonの自動計装（ログ連携のための設定） 2025/11/6 25 • 標準ロギングライブラリの「logging」でloggerを作成 • 作成したloggerでログを出力すると自動でログの中に 「trace_id」と「span_id」などが出力される import logging logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) logger.info(f"Inventory reserved with pricing") # 2025-10-29 05:28:03,930 INFO [main] [main.py:103] [trace_id=6901a5e3cf4d6eb7a0c751e96a15cd75 span_id=0b2f65c94897a756 resource.service.name=python-fastapi-service trace_sampled=True] - Inventory reserved with pricing
26. Pythonの自動計装（Exemplars） 2025/11/6 26 • OpenTelemetry SDKでExemplarsのサポート自体はされてい る（※） が、各instrumentationの方でMetricにTrace IDやSpan IDを追加する処理がまだ実装されてない。 つまり、自動生成されるメトリクスは連携されるが、Metricから Traceへの遷移はできない。 ※ https://github.com/open-telemetry/opentelemetry-python/issues/2407
27. Pythonの自動計装（全体像） 2025/11/6 27 • Pythonの場合、「OTEL_METRICS_EXPORTER」を prometheusにしても、JavaのようにPrometheusのスクレ イピングエンドポイントは作成されないので、Metricもotlp で直でADOT Collectorに連携 ADOT Collector AWS for Fluent Bit Tempo Loki Trace Metric Log Log Metric Trace
28. 2025/11/6 28 Node.js（JavaScript）の自動計装
29. Node.js（JavaScript）の自動計装 2025/11/6 29 • 「@aws/aws-distro-opentelemetry-node- autoinstrumentation」パッケージをインストールし、以下 の環境変数を設定の上、「--require '@aws/aws-distro- opentelemetry-node-autoinstrumentation/register'」を 付けて実行するだけ $ npm install @aws/aws-distro-opentelemetry-node-autoinstrumentation $ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \ OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \ OTEL_LOGS_EXPORTER=otlp \ OTEL_METRICS_EXPORTER=otlp \ OTEL_TRACES_EXPORTER=otlp \ OTEL_SERVICE_NAME=<サービス or システム名> $ node --require '@aws/aws-distro-opentelemetry-node-autoinstrumentation/register' app.js
30. Node.js（JavaScript）の自動計装（ログ連携のための設定） 2025/11/6 30 • ロギングライブラリ「winston」、「pino」、「bunyan」のいずれかで loggerを作成 • 作成したloggerでログを出力すると自動でログの中に 「trace_id」と「span_id」などが出力される const winston = require('winston'); const logger = winston.createLogger({ level: 'info’, format: winston.format.combine( winston.format.timestamp(), winston.format.json() ), transports: [new winston.transports.Console()] }); logger.info('Retrieved inventory items', { count: rows.length }); # {"count":3,"level":"info","message":"Retrieved inventory items","span_id":"6251b344104f74b5","timestamp":"2025-10- 29T06:25:55.737Z","trace_flags":"01","trace_id":"6901b373d750f74a962e86a272143266"}
31. Node.js（JavaScript）の自動計装（全体像） 2025/11/6 31 • Pythonと同様 ADOT Collector AWS for Fluent Bit Tempo Loki Trace Metric Log Log Metric Trace
32. 2025/11/6 32 Goの自動計装
33. Goの自動計装 2025/11/6 33 • JavaやPythonのようにコードの変換ができず、コードレベルでの 自動計装はできない • 回避策 ➢ eBPF ➢ ServiceMesh ➢ 手動計装
34. ※eBPFとは 2025/11/6 34 • 特定のsystem callにアタッチして、system callイベント発生時に ある処理（eBPFプログラム）を実行することができる仕組み • ネットワーク（e.g. Cilium）、オブザーバビリティ（e.g. Beyla）、 セキュリティ（e.g. Falco）関連ツールで、多く利用されている
35. Goの自動計装（eBPF） 2025/11/6 35 • eBPFプログラムで特定のGoバイナリファイルより実行されたプロ セスからの、サポートしているライブラリ関数の呼び出しをキャッチ し、Traceデータを生成・連携する • ただ、サポートするライブラリは以下の４つだけで限定的（※1） ➢ 「database/sql」 ➢ 「github.com/segmentio/kafka-go」 ➢ 「google.golang.org/gprc」 ➢ 「net/http」 • 足りないトレースデータを補うため、手動計装との併用も可能（※２） ※1 https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/COMPATIBILITY.md ※2 https://opentelemetry.io/docs/zero-code/go/autosdk/#how-do-i-use-it
36. Goの自動計装（eBPF）（Docker-composeの設定例） 2025/11/6 36 ※ https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/getting-started.md go-service: image: go-service-ebpf:latest build: context: ./go-service-ebpf dockerfile: Dockerfile container_name: go-service pid: "host" ports: - "8080:8080" volumes: - ./data:/data go-auto-instrumentation: image: otel/autoinstrumentation-go:latest container_name: go-auto-instrumentation privileged: true pid: "host" environment: - EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 - OTEL_GO_AUTO_TARGET_EXE=/app/go-service # 対象のgoバイナリを指定 - OTEL_SERVICE_NAME=go-gin-ebpf-service - OTEL_PROPAGATORS=tracecontext,baggage - OTEL_TRACES_EXPORTER=otlp - OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf volumes: - /proc:/host/proc
37. eBPFの制約 2025/11/6 37 • カーネルにeBPFプログラムのロードなど、 カーネルへのアクセス権限が必要 • Fargateなど、OS層が抽象化されている基盤では利用不可（※） ※ECS Managed Instanceでは利用可能 https://docs.aws.amazon.com/AmazonECS/latest/developerguide/managed-instances-capacity-providers-concept.html
38. ※補足： OBI （OpenTelemetry eBPF Instrumentation） 2025/11/6 38 • https://opentelemetry.io/ja/docs/zero-code/obi/ • eBPFを使った自動計装 • Kubernetes、Docker、バイナリ、３つのタイプの実行をサポート • Ruby、C、Rustなど幅広い言語をサポート
39. Goの計装（ServiceMesh） 2025/11/6 39 • アプリケーションコンテナのサイドカーコンテナとしてServiceMesh （e.g. Envoy）コンテナを起動 • ServiceMeshコンテナがアプリへの通信、アプリからの通信を インターセプトして、通信内容に関してトレースデータを生成し、 Backendに送信
40. ServiceMeshの制約 2025/11/6 40 • アプリケーションはトレースの存在について知らないため、 ヘッダーにあるContextを伝播するよう、コードの修正が必要
41. Goの計装（手動計装） 2025/11/6 41 • OpenTelemetry Go SDKを使って直接Trace（Span）データを 生成し、バックエンド（e.g. ADOT Collector、 Tempo）に連携 • 基本的な使い方（Trace） 1. Resourceを定義 2. Expoterを定義 3. TraceProviderを定義 4. Tracerを定義 5. 定義したTracerでSpanを生成
42. Goの計装（手動計装の具体的な実装例） 1/４ 2025/11/6 42 import ( "context" "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp" "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp" "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp" otlog "go.opentelemetry.io/otel/log" "go.opentelemetry.io/otel/log/global" "go.opentelemetry.io/otel/propagation" sdklog "go.opentelemetry.io/otel/sdk/log" sdkmetric "go.opentelemetry.io/otel/sdk/metric" "go.opentelemetry.io/otel/sdk/resource" sdktrace "go.opentelemetry.io/otel/sdk/trace" semconv "go.opentelemetry.io/otel/semconv/v1.21.0" "go.opentelemetry.io/otel/trace" ) • Otel関連パッケージをimport
43. Goの計装（手動計装の具体的な実装例） 2/４ 2025/11/6 43 • Resource、Exporterを定義 // Resource res, err := resource.New(ctx, resource.WithAttributes( // セマンティック規約に則ったResource Attributeを追加 semconv.ServiceName(“go-gin-service”), semconv.ServiceVersion("1.0.0"), ), ) if err != nil { return nil, fmt.Errorf("failed to create resource: %w", err) } // Trace exporter traceExporter, err := otlptracehttp.New(ctx, otlptracehttp.WithEndpoint(“localhost:4318”), // 送り先を指定 otlptracehttp.WithInsecure(), // 送り先としてhttpを使う場合 ) if err != nil { return nil, fmt.Errorf("failed to create trace exporter: %w", err) }
44. Goの計装（手動計装の具体的な実装例） ３/４ 2025/11/6 44 • Trace Provider、Tracerを定義 // Trace provider tracerProvider := sdktrace.NewTracerProvider( sdktrace.WithBatcher(traceExporter), // batch processorの引数として前で設定したExpoterを指定 sdktrace.WithResource(res), // 前で設定したResourceを指定 ) otel.SetTracerProvider(tracerProvider) // SetTracerProviderの引数として上のtracerProviderを指定 otel.SetTextMapPropagator(propagation.TraceContext{}) tracer = tracerProvider.Tracer("go-service-tracer")
45. Goの計装（手動計装の具体的な実装例） ４/４ 2025/11/6 45 • 作成したTracerでSpanデータを生成 r.POST("/pricing/calculate", func(c *gin.Context) { ctx := c.Request.Context() sql := "SELECT unit_price FROM pricing WHERE product_name = ?” // Span計測開始 dbCtx, dbSpan := tracer.Start(ctx, "db_select_pricing", trace.WithAttributes( attribute.String(“db.operation.name”, “select”),// 必要に応じてspanにAttributeを追加 attribute.String("db.collection.name", "pricing"), attribute.String("db.query.text", sql), ), ) var unitPrice float64 err := db.QueryRowContext(dbCtx, sql, req.ProductName).Scan(&unitPrice) // Span計測終了 dbSpan.End()
46. まとめ 2025/11/6 46 • まずは自動計装から始めて、テレメトリデータの内容を確認 • 自動計装で取得されるデータだけでは足りないケースについては、 手動計装と組み合わせてデータを充実させる • 言語の制約を理解した上で、環境に合った代替手段を選択