Next.jsとOpenTelemetry

OTelにはAPIとSDKがある
APIは型定義、SDKにはその実体や実際に計装するために必要なもろもろが入っている
またそれぞれには仕様と実装がある
https://opentelemetry.io/docs/specs/otel/
https://github.com/open-telemetry/opentelemetry-js

トレースについて

APIはTracerProvider→Tracer→Spanの三層構造
TracerProviderは共通の設定やTracerの生成、TracerはSpanの生成を行う
TracerProviderにはNodeTracerProviderとWebTracerProviderがある

三層構造はメトリクス、ログでも現れる
MeterProvider→Meter→Instrument
LoggerProvider→Logger→LogRecord

普通はGlobalProviderが1つあり、アプリケーションや計装を行うライブラリはそこからTracer/Meter/Loggerを生成する
https://pkg.go.dev/go.opentelemetry.io/otel/trace@v1.14.0#TracerProvider

TracerProviderではいくつか設定を行う

Resource
テレメトリデータが生成された環境についての情報
サービス名やブラウザの情報が入る
https://github.com/YunosukeY/next-otel-sample/blob/main/src/otel/web/webResource.ts#L5-L11

TraceExporter
トレースの出力方法を指定する
JSではデバッグ用のConsoleTraceExporter, テスト用のInMemoryTraceExporter, アプリケーション用のOTLPTraceExporterがある
Exporterについてはメトリクス、ログも同様

SpanProcessor
トレースの出力タイミングを指定する
JSには即座に出力するSimpleSpanProcessor, バッチ処理するBatchSpanProcessorがある
Simple〜はデバッグ、テスト用、Batch〜はアプリ用
Processorについてはログも同様

ContextManager
OTelのコンテキストは異なるサービス間で情報をやりとりする仕組み
利用にはContextManagerが必要
ブラウザJSではZoneContextManagerとStackContextManagerがあり、非同期処理をトレースするにはZoneContextManagerが必要
Node.jsにはAsyncHooksContextManagerとAsyncLocalStorageContextManagerがあり、パフォーマンス、メモリ安全性、既知の不具合からAsyncLocalStorageContextManagerの方が良さそう

Propagator
異なるサービス間でコンテキストを伝播させる
JSにはW3CTraceContextPropagator、W3CBaggagePropagatorがある
トレースの場合はW3CTraceContextPropagatorを使う？

WebTracerProviderの設定は最終的にこうなった
https://github.com/YunosukeY/next-otel-sample/blob/main/src/otel/web/webTracer.ts#L13-L21

自動計装の設定
https://github.com/YunosukeY/next-otel-sample/blob/main/src/otel/web/webTracer.ts#L23-L29

Tracerの生成と手動計装
https://github.com/YunosukeY/next-otel-sample/blob/main/src/otel/web/webTracer.ts#L31
https://github.com/YunosukeY/next-otel-sample/blob/main/src/ClientOTelExamples/ClientFetchTraceExample.tsx#L5-L18
実際には関数を渡したらスパン付きで実行してくれるような関数を作った方が良いだろう

OTel Collectorはクロスオリジンになるのでプロキシしておく
https://github.com/YunosukeY/next-otel-sample/blob/main/next.config.mjs#L6-L11

メトリクスについて

メトリクスの場合はMetricExporterとMetricReaderの設定をする
JSのMetricReaderには定期的にメトリクスをpushするPeriodicExportingMetricReaderがある
https://github.com/YunosukeY/next-otel-sample/blob/main/src/otel/web/webMeter.ts#L9-L20
https://github.com/YunosukeY/next-otel-sample/blob/main/src/ClientOTelExamples/ClientMetricsExample.tsx#L5-L18
トレースと同様にプロキシする

ログについて

https://github.com/YunosukeY/next-otel-sample/blob/main/src/otel/web/webLogger.ts#L9-L15
https://github.com/YunosukeY/next-otel-sample/blob/main/src/ClientOTelExamples/ClientLogExample.tsx#L5-L13
実際にはLoggerのラッパークラスを作った方が良さそう

ここまではブラウザJSの話
ここからNode.jsの話

Next.jsには@vercel/otelというパッケージがあるがこれは不要
中身はNodeSDKを薄くラップしているだけ
https://blog.ojisan.io/next-otel/

Next.jsのデフォルトスパンは便利なので有効にする
https://nextjs.org/docs/app/building-your-application/optimizing/open-telemetry

Node.js側にはProviderの生成とGlobalProviderへのセットを行うSDKがあるのでこれを利用する
https://github.com/YunosukeY/next-otel-sample/blob/main/src/otel/node/nodeSdk.ts#L9-L34

実際の手動計装はブラウザJSと同様

動作確認は以下を利用
https://github.com/vercel/opentelemetry-collector-dev-setup

ログには対応していないので設定を追加する必要がある
OTel Collectorのログのexportersはloggingしかない
以下をservice.pipelinesに追記

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]

Ctrl+Cで止めてもテレメトリデータが送られ続けたことがあったので以下があった方が良いかも
https://github.com/YunosukeY/next-otel-sample/blob/main/package.json#L6-L8
https://github.com/YunosukeY/next-otel-sample/blob/main/src/instrumentation.node.ts#L5-L12

ブラウザJSの方は上手い実装が思いつかなかったのと、変な状況にならなかったので不要かも