モニタリング・データ(メトリックおよびトレース)をApplication Performance MonitoringにアップロードするためのOpenTelemetry (ホテル)データ・ソース(インストゥルメンテーション・ライブラリやOpenTelemetryコレクタなど)の構成について説明します。

const opentelemetry = require("@opentelemetry/sdk-node");
const {
 getNodeAutoInstrumentations,
} = require("@opentelemetry/auto-instrumentations-node");
const {
 OTLPTraceExporter,
} = require("@opentelemetry/exporter-trace-otlp-http");

  const sdk = new opentelemetry.NodeSDK({
traceExporter: new OTLPTraceExporter({
  url: "https://aaabbbb.example.us-phoenix-1.oci.oraclecloud.com/20200101/opentelemetry/private/v1/traces",
  headers: {"Authorization": "dataKey AAAAABBBBBCCCC"},
 }),

  instrumentations: [getNodeAutoInstrumentations()]
});

 sdk.start()
(base) [ssirajud@ssirajud node_with_opentelemetry]$

export OTEL_TRACES_EXPORTER=otlp
export OTEL_SERVICE_NAME=my-service
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="authorization=dataKey 1111aaaabbbccc"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://aaabbbb.example.us-phoenix-1.oci.oraclecloud.com/20200101/opentelemetry/private/v1/traces/
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://aaabbbb.example.us-phoenix-1.oci.oraclecloud.com/20200101/opentelemetry/v1/metrics
export OTEL_EXPORTER_OTLP_METRICS_HEADERS="authorization=dataKey 1111aaaabbbccc"
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf

ここでは、分散トレースにJaegerクライアントを使用するJavaアプリケーションのコードに対して行う必要のある変更について説明します。これを使用して、トレースをApplication Performance Monitoringにアップロードします。

Jaegerトレーサを使用してトレースをJavaアプリケーションからApplication Performance Monitoringにアップロードするには、Jaeger JavaクライアントをZipkin互換のために構成し(Zipkin v2形式のレポート)、Application Performance MonitoringコレクタURLを追加する必要があります。これを行うには、サービスのコードを次のように変更する必要があります:

1. 必要なJaegerクライアント依存関係とともに、pom.xmlファイルに次の依存関係を追加します。

   <dependency>
       <groupId>io.zipkin.reporter2</groupId>
       <artifactId>zipkin-sender-urlconnection</artifactId>
       <version>2.15.0</version>
   </dependency>
   <dependency>
       <groupId>io.jaegertracing</groupId>
       <artifactId>jaeger-zipkin</artifactId>
       <version>1.3.2</version>
   </dependency>

2. ZipkinV2Reporterを使用して、Zipkin 2レポータをJaegerレポータ・インタフェースに適応させ、JaegerスパンをJSONエンコードされたZipkin v2フォーマットに変換します。スパンをApplication Performance MonitoringにアップロードするためのApplication Performance MonitoringコレクタURLと、サービスまたはアプリケーションの名前を指定したことを確認します。

   import io.jaegertracing.Configuration;
   import io.jaegertracing.zipkin.ZipkinV2Reporter;
   import zipkin2.reporter.AsyncReporter;
   import zipkin2.reporter.urlconnection.URLConnectionSender;
    
   /* .... */
    
   ZipkinV2Reporter reporter = new ZipkinV2Reporter(AsyncReporter.create(URLConnectionSender.create("<Application Performance Monitoring collector URL>")));
   JaegerTracer tracer = Configuration
       .fromEnv("<service-name>")
       .getTracerBuilder()
       .withReporter(reporter)
       .withSampler(new ConstSampler(true))
       .build();
    
   /* .... */

3. B3伝播(b3ヘッダーの仕様)を使用するために、B3TextMapCodecを登録します。これらのヘッダーは、サービス境界をまたぐトレース・コンテキスト伝播に使用されます。

   import io.jaegertracing.Configuration;
   import io.jaegertracing.internal.propagation.B3TextMapCodec;
   import io.opentracing.propagation.Format;
    
   /* .... */
    
   B3TextMapCodec b3Codec = new B3TextMapCodec.Builder().build();       
   JaegerTracer tracer = Configuration
       .fromEnv("<service-name>")
       .getTracerBuilder()
       .registerInjector(Format.Builtin.HTTP_HEADERS, b3Codec)
       .registerExtractor(Format.Builtin.HTTP_HEADERS, b3Codec)
       .build();
    
   /* .... */

   環境構成(Configuration.fromEnv())を使用してJaegerトレーサを作成する場合、JAEGER_PROPAGATION環境変数をb3cに設定すると、コードの変更なしでZipkin(B3)コンテキスト伝播モードが設定されることに注意してください。

ここでは、分散トレースにZipkinクライアントを使用するNode.jsアプリケーションのコードに対して行う必要のある変更について説明します。これを使用してトレースをApplication Performance Monitoringにアップロードします。

これを行うには、Zipkinトレーサ初期化コードを次のように変更します:

1. JSONエンコードされたZipkin v2フォーマットでスパンをレポートするために必要な変更を加えたことを確認します。

   Zipkinのv2形式の詳細は、Zipkin 2を参照してください。

2. スパンをApplication Performance MonitoringにアップロードするためのApplication Performance MonitoringコレクタURLと、サービスまたはアプリケーションの名前を追加します。
3. Zipkinのスパン結合機能が有効になっている場合は、無効にします。OpenTracing仕様では、同じトレース内の異なるスパン間でスパンIDを共有できないため、この機能は無効にする必要があります。

Node.jsの例

ここでは、Zipkinトレーサ初期化コードのサンプルを示します。手順で説明されている変更部分は太字になっています。

const {
  Tracer,
  BatchRecorder,
  jsonEncoder: {JSON_V2}
} = require('zipkin');
 
const CLSContext = require('zipkin-context-cls');
const {HttpLogger} = require('zipkin-transport-http');
 
// Setup the tracer
const tracer = new Tracer({
  ctxImpl: new CLSContext('zipkin'), // implicit in-process context
  recorder: new BatchRecorder({
    logger: new HttpLogger({
      endpoint: '<Application Performance Monitoring collector URL>', //Span collection endpoint URL setting
      jsonEncoder: JSON_V2 //Span format and encoding setting
    })
  }), // batched http recorder
  localServiceName: '<service-name>', // name of the application/service
  supportsJoin: false //Span join disable setting
});

Application Performance Monitoringサービスと通信するようにオープンソース・トレーサを構成する際には、Application Performance MonitoringコレクタURLが必要です。このトピックでは、APMコレクタURLフォーマットの詳細を示します。

Application Performance MonitoringコレクタURLのフォーマットは次のとおりです:

<dataUploadEndpoint>/<API version>/observations/<observationType>?dataFormat=<dataFormat>&dataFormatVersion=<dataFormatVersion>&dataKey=<dataKey>

APMドメインの詳細ページから<dataUploadEndpoint>値を取得します。

https://aaaabbbb.example.us-ashburn-1.oci.oraclecloud.com/20200101/observations/public-span?dataFormat=zipkin&dataFormatVersion=2&dataKey=11115Q7IGN

spring.zipkin.baseUrl =  https://aaaabbbb.example.us-ashburn-1.oci.oraclecloud.com
spring.zipkin.apiPath = /20200101/observations/public-span?dataFormat=zipkin&dataFormatVersion=2&dataKey=11115Q7IGN

https://aaaabbbb.example.us-phoenix-1.oci.oraclecloud.com/20200101/observations/private-span?dataFormat=otlp-span&dataFormatVersion=1&dataKey=11112222UZ5

コンテキスト伝播を構成して、適切な形式で伝播されたトレース・コンテキスト情報を取得し、それを1つ以上のHTTPリクエスト・ヘッダーに追加します。トレース・コンテキストを使用すると、異なるマイクロサービスから発生するが同じトランザクション(トレース)に属し、共通のトレースIDで識別されるスパンを相関させることができます。

APMエージェント/トレーサ

完全なトレースを作成するために、APM Javaエージェント/トレーサを他のOpenTracingトレーサ(JaegerやZipkinなど)と連携するように構成できます。

HTTPコールが発生すると、APM Javaエージェント/トレーサはHTTPヘッダーをそのコールに追加しようとします。反対側の端でこれが読み取られると、スパン同士を結合するのに役立ちます。

この形式は、oracle-apm-agent\configディレクトリにあるAgentConfig.propertiesファイルのcom.oracle.apm.agent.tracer.propagation.typeプロパティを使用して変更できます。

プロパティを名前に設定することで、次の伝播タイプを利用できます:

各種のトレーサが連携して完全なトレースを形成できるように、適切な伝播タイプを設定します。

OpenTelemetry、Zipkin & Jaeger