OpenTelemetryとは？

このドキュメントでは、OpenTelemetryを使用したソフトウェアのオブザーバビリティ（可観測性）の概念について紹介します。OpenTelemetryとそのコンポーネント、テレメトリーに関連するシグナルの種類、すなわちログ、メトリクス、トレースについて詳しく説明します。さらに読み進めることで、これらのシグナルの生成方法とOpenTelemetry Collectorの使用方法について学ぶことができます。

テレメトリーの概要

テレメトリーとは、ログ、メトリクス、トレースから収集されるデータのことで、測定値として経験的価値を提供し、システムへの洞察を与えます。テレメトリーデータは、様々なシステムで有効にすることができ、その一部には以下のようなものがあります。

• 受信したリクエスト数の把握
• 発生したイベントのロギング
• マシン上のメモリー消費量を明確な経験値として記録
• クライアントからバックエンドへのリクエストの追跡

テレメトリーデータは、適切に分析されると、以下の点で役立ちます。

• システム内の障害の原因を特定し、証拠を提供する
• 何が問題だったのかを理解する
• 複雑なシステムで発生するイベントについて学習する

テレメトリーデータは、システムに関する貴重な洞察を明らかにするために、分析し、適切に可視化する必要があります。データを分析するための様々なツールやベンダーが存在する一方で、OpenTelemetryは、これらのテレメトリーデータをベンダーに依存しない方法でキャプチャするための統一された標準的なフレームワークを提供します。これにより、任意のツールを使用してソフトウェアのパフォーマンスに関する洞察を得ることができます。

この記事では、OpenTelemetryとその使用方法について詳しく掘り下げていきます。これは、集中ロギング、メトリクスとダッシュボード、トレース、データ分析など、クラウドネイティブのソフトウェア開発者がすでに使用している技術のために構築されたツールスイートであることに留意してください。

OpenTelemetryの概要

OpenTelemetryは、OpenTracingとOpenCensusを統合したオープンソースプロジェクトです。後者（OpenCensus）は、アプリケーションでメトリクスと分散トレースを収集するためのライブラリセットでしたが、現在はOpenTelemetryに統合されています。Cloud Native Computing Foundation（CNCF）は、テレメトリーデータの収集とバックエンドサービスへの送信を標準化することを目標に、OpenTelemetryプロジェクトに資金を提供しています。

プロジェクトとしてのOpenTelemetryには、いくつかの仕様、API、プログラミング言語用のSDK、ライブラリ、および統合サポートがあります。オープンソースプロジェクトであるOpenTelemetryは、300社以上の企業と10万件以上のコントリビューションによって構築・維持されています。

OpenTelemetryには様々な機能があり、OpenTracingとOpenCensusの最良の組み合わせの1つであり、開発者にとって最も広く採用されているオブザーバビリティツールとなっています。これらの機能には、以下が含まれます。

• オープンな仕様
• 言語固有のクライアントのためのAPIとSDK
• 計装ライブラリ
• セマンティック規約
• テレメトリーデータを収集するエージェント
• データを整理、送信、受信するための媒体

OpenTelemetryは、エージェントをインストールしたり、コードを書き換えたりするだけで、オブザーバビリティのためのお好みのバックエンドツールを選択できる十分な柔軟性を提供します。

OpenTelemetryのコンポーネント

OpenTelemetryは、それぞれが独自の構成方法とプロジェクトへの関連性を持つ、幅広いツールのエコシステムで構成されています。個々のプロジェクトは、シグナル、パイプライン、リソース、コンテキスト伝播で構成されます。

シグナル

OpenTelemetryでは、シグナルはプロジェクトで重要な役割を果たし、当初はトレース、メトリクス、ログ、およびBaggageとして定義されていました。OpenTelemetryのシグナルには、以下のプロパティが含まれます。

• シグナルを実装するためのガイダンスを提供する文書化された仕様
• 実装中にシグナルがどのように表現されなければならないかを示すデータモデル
• アプリケーションおよびライブラリ開発者がコードを構築するためのAPI
• ユーザーがAPIを使用してテレメトリーを生成できるようにするSDK
• 一貫性のある価値あるデータのみを対象とするためのセマンティック規約
• シグナルの使用と採用を簡素化する計装ライブラリ

シグナルについては、以下でさらに詳しく説明します。

パイプライン

パイプラインは、シグナルがキャプチャしたテレメトリーデータを生成、処理し、ストレージと分析のためにデータストアにエクスポートするメカニズムです。

伝送中に意味のあるデータが失われないように、パイプラインコンポーネントはアプリケーションコードの早い段階で作成されます。コンポーネントは以下の通りです。

• レシーバー：データをOpenTelemetry Collectorに転送します。レシーバーはプッシュベースまたはプルベースのいずれかです。
• プロセッサー：生成されたテレメトリーデータの内容を変更し、データをエクスポートする媒体を決定します。
• エクスポーター：OpenTelemetryが使用する内部データ形式から、構成を介してエクスポーターが理解できる別の形式にデータを変換します。例：
  • Jaeger
  • Zipkin
  • OpenTelemetryプロトコル
  • Prometheus

これらのコンポーネントは、レシーバー → プロセッサー → エクスポーターの順序でなければなりません。

これらのコンポーネントについては、次のセクションで詳しく説明します。

リソース

リソースは、テレメトリーデータのソースを識別するために、さまざまなシグナルに適用される属性です。これらは、同じリソースで発生するさまざまなイベントを相関させてテレメトリーデータを分析するのに役立つ情報を収集します。

リソース属性は、データソースがマシン、コンテナ、または関数であるかを識別するため、アプリケーションのライフタイムを通じて変更されません。リソース属性には、以下が含まれます。

• service.name：サービスを説明する一意の名前
• service.version：サービスのバージョン識別子
• host.name：デバイスを実行しているホストの名前

コンテキスト伝播

コンテキスト伝播は、論理的な境界で分離された2つのサービス間で価値のあるコンテキストデータを送信できるようにする、OpenTelemetryのコアコンポーネントです。これにより、分散トレーシングで複数のシステムにまたがるリクエストを組み合わせることができます。

コンテキストオブジェクトは、APIの境界を越えて渡されるキーと値のストアです。そのため、コンテキストの実装は言語に依存する操作です。PythonやGoのようなプログラミング言語には、ContextVarモジュールやcontextパッケージなど、独自の組み込みコンテキストメカニズムがあります。OpenTelemetryのAPI仕様では、コンテキストAPIの実装でこれらの既存のメカニズムを活用することが推奨されています。

OpenTelemetryクライアントアーキテクチャ

完全なOpenTelemetryクライアントアーキテクチャには、ソフトウェアライブラリのコレクションをインストールする必要があります。これらのライブラリには、以下が含まれます。

• アプリケーションロジックを計装するために使用される一連のコンポーネントを提供する計装API
• プラグインフレームワークを提供することでAPIを実装するSDK
• コンテキスト伝播で役割を果たし、HTTPクライアントとサーバー、メッセージキューイングシステム、アプリケーションフレームワーク、およびデータベースクライアントを提供する計装ライブラリ
• レシーバー、プロセッサー、エクスポーター、およびパイプラインを含むように構成されたOpenTelemetry Collector

シグナル—テレメトリーの関連カテゴリ

OpenTelemetryの文脈では、シグナルはデータ共有メカニズム（すなわち、コンテキスト伝播）の上に構築された、独立したオブザーバビリティツールです。現在、サポートされているシグナルは、トレース、メトリクス、ログ、Baggageの4つです。このセクションでは、これらの柱について詳しく説明します。

ログ

ログは、リクエストサイクル内のイベントを記録し、出力に書き込まれます。ログ出力は通常、検索性と集計を向上させるために、ディスク上のファイルまたはリモートサービスに書き込まれます。ログの構成要素は以下の通りです。

• 各イベントの時刻を記録するタイムスタンプ
• イベントを表すメッセージ/ペイロード

ペイロードの例は次のとおりです。

169.10.0.19 - - [11/Nov/2022 11:42:35] "GET /inventory HTTP/1.1" 200 -

より多くのコンテキストを提供するために、ログは通常、相関関係を通じて他のシグナルタイプと組み合わせられます。

トレース

OpenTelemetryのトレーシングシグナルは、システム内の分散トレーシングを担当します。トレースとは、システムのさまざまなポイントで生成され、一意の識別子によって束ねられた一連のイベントデータです。

識別子はリクエストのサイクルに関わる他のすべてのコンポーネントに転送され、それらの操作がデータソースからイベントデータにアクセスできるようになります。スパンコンテキストにおけるトレースの完全な構成要素には、これらの要素が含まれます。

• traceID：関連するトレースの一意の識別子
• spanID：トレース内の現在のメソッドの一意の識別子
• トレースフラグ：トレースに関する追加情報（サンプリングやトレースレベルなど）を含みます。
• トレース状態フィールド：トレーシングデータの解釈に役立つベンダー固有の情報を保持します。

文脈上、スパンはメソッド呼び出し、またはメソッド内で呼び出されるコードブロックのサブセットとして説明できます。

例えば、以下のワークフローを持つショッピングアプリケーションでは、各独立したワークフローが1つのトレースと考えることができます。

• クライアントアプリケーションがインターネットにアクセスする。
• オンラインショッピングのWebアプリが読み込まれる。
• ユーザーが商品の在庫を確認するたびに、Webアプリが在庫APIに接続する。
• 在庫APIが店舗で商品をチェックし、注文APIを呼び出す。
• ユーザーが商品を注文すると、注文キューに入れられる。
• 該当する場合、購入した商品はユーザーの注文履歴に追加される。
• 注文キューを経た後、購入が完了する。
• 通知サービスがユーザーとショップオーナーの両方に呼び出される。

OpenTelemetryの分散トレーシングを使用すると、トレースコンテキスト（traceparentヘッダー）を伝播させることで、これらすべてをリンクさせ、ワークフローの全体像を把握できます。

メトリクス

メトリクスは、実行中のアプリケーションやシステムの状態に関する情報を開発者やオペレーターに提供します。時間の経過とともに、メトリクスデータが収集・集計され、システム内のパターンや傾向を特定し、さまざまなツールや可視化機能を使ってグラフに変換されます。

メトリクスには幅広い種類があり、低レベルのシステム（CPUサイクル）から高レベルの詳細（1日に販売されたアイテム数）まで、両方のデータをキャプチャできます。

記録されたデータがメトリクスと見なされるためには、その構成要素として以下のプロパティを持つ必要があります。

• 記録されるメトリクスの名前
• 経験的なデータポイント値
• メトリクスに関する追加の次元情報

メトリクスをトレースと組み合わせることで、システムで発生しているイベントについて、より深い情報とコンテキストを得ることができます。OpenTelemetryでは、この組み合わせは、定義時にExemplarフィールドに含まれるExemplarによって可能になります。このフィールドには以下が含まれます。

• スパンのトレースID
• スパンのスパンID
• 測定対象イベントのタイムスタンプ
• Exemplarに関連する属性のセット
• 記録されている値

OpenTelemetryのExemplarを使用すると、特定のトレースやスパンをログメッセージ、メトリクス、またはその他のデータに添付できます。これは、トラブルシューティングやアプリケーションの動作パターンの特定に役立ちます。

Go SDKでOpenTelemetryのExemplarを使用する例を次に示します。

package main
import (
"context"
"go.opentelemetry.io/otel/api/trace"
)
// グローバルトレーサープロバイダーからトレーサーを取得
tracer := trace.GlobalTracer()
// 新しいスパンを開始
ctx, span := tracer.Start(context.Background(), "my_span")
defer span.End()
// スパンにいくつかの属性を設定
span.SetAttributes(
trace.StringAttribute("key", "value"),
)
// スパンのExemplarを作成
exemplar := &trace.Exemplar{
Value: 42,
Timestamp: span.StartTime(),
Attachments: map[string]interface{}{
"trace_id": span.SpanContext().TraceID,
"span_id": span.SpanContext().SpanID,
},
}
// Exemplarをログメッセージに添付
logger.Infof("My log message", exemplar)
// Exemplarをメトリクスや他のデータに添付することも可能
metric.Record(ctx, exemplar)

この例では、新しいスパンを作成し、それにいくつかの属性を設定しました。次に、スパンのExemplarを作成し、valueとtimestampフィールドを設定するとともに、スパンのコンテキストからtrace_idとspan_idを添付しました。最後に、exemplar引数を使用してexemplarをログメッセージとメトリクスに添付しました。

これにより、ログメッセージ、メトリクス、またはその他のデータを、関連付けられている特定のトレースとスパンにリンクバックさせることができます。

計装ライブラリ

サードパーティ製ツール向けの計装ライブラリは、OpenTelemetryを使用するユーザーからの最小限の労力で済みます。OpenTelemetry用の計装ライブラリは、一般的なプログラミング言語でいくつか利用可能です。ほとんどは、自動および手動の両方の計装、およびこれらの言語でのデータエクスポートをサポートしています。

システムの全体像を把握するためには、HTTPクライアント＆サーバー、アプリケーションフレームワークライブラリ、およびデータベース、キューイングシステムなどの他の必要なコンポーネントを含む、アプリケーションのインフラストラクチャ全体でOpenTelemetryの計装を行う必要があります。

このセクションでは、計装ライブラリの設定方法と使用方法について説明します。いずれかの計装ライブラリを使用してOpenTelemetryを計装するプロセスは同じです。

• テレメトリーをオブザーバビリティバックエンド（Jaeger、Zipkin、OpenTelemetry HTTP、gRPCなどのシステムを使用）またはOpenTelemetry Collectorに送信する
• トレースプロバイダーとスパンプロセッサー（SimpleSpanProcessorなど）を定義する
• 追加のコンテキストを追加するためのリソースを定義する
• バックエンドに送信されるトレースサンプルの数を制御するサンプラー（AlwaysOnSamplerなど）を定義する

OpenTelemetryでサポートされているライブラリはすべてここに記載されています。ただし、次のセクションではGoの計装ライブラリを参照します。

GoでOpenTelemetryを使用する方法

GoのOpenTelemetryサポートライブラリは、現在以下のステータスをカバーしています。

• トレーシング：安定版
• メトリクス：アルファ版
• ロギング：未実装

カスタムメトリクス実装

メトリクスの計装には、PrometheusとGoのOpenTelemetryクライアントを使用します。以下のライブラリをインポートします。

import (
"context"
"fmt"
"log"
"math/rand"
"net/http"
"os"
"os/signal"
"time"

"github.com/prometheus/client_golang/prometheus/promhttp"

"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/exporters/prometheus"
"go.opentelemetry.io/otel/metric/instrument"
"go.opentelemetry.io/otel/sdk/metric"
)

このために、Webリクエストを受信し、処理して応答するデモアプリケーションを作成します。リクエストレート、エラーレート、および処理レイテンシー分布を追跡します。読み取りと収集を処理するエクスポーターを作成しましょう。

func init() {
rand.Seed(time.Now().UnixNano())
}// このセクションの残りのコードはfunc mainの下にあります
func main() {
exporter, err := prometheus.New()
if err != nil {
log.Fatal(err)
}

次に、メトリクスをOpenTelemetry Collectorに送信するようにエクスポーターを設定することで、メトリクスの計装を追加できます。次に、メトリクスをクエリするためのサービスの情報を含むメータープロバイダーが定義されます。

provider := metric.NewMeterProvider(metric.WithReader(exporter))
meter := provider.Meter("github.com/…/prometheus")

Prometheusサーバーを起動し、収集を開始します。

go serveMetrics() // prometheusサーバー関数は以下で作成

attrs := []attribute.KeyValue{
attribute.Key("A").String("B"),
attribute.Key("C").String("D"),
}

カウンターベクターのロジック：

counter, err := meter.SyncFloat64().Counter("foo", instrument.WithDescription("a counter for demonstration"))
if err != nil {
log.Fatal(err)
} counter.Add(ctx, 5, attrs...)

gauge, err := meter.AsyncFloat64().Gauge("bar", instrument.WithDescription("a gauge for demonstration")) if err != nil {
log.Fatal(err)
}
err = meter.RegisterCallback([]instrument.Asynchronous{gauge}, func(ctx context.Context) {
n := -10. + rand.Float64()*(90.) // [-10, 100)
gauge.Observe(ctx, n, attrs...)
})
if err != nil {
log.Fatal(err)
}

その後、リクエストとエラーを追跡するためのインクリメントカウンターと、レイテンシーを追跡するためのPrometheusのものと同様のヒストグラムベクターを使用して、実際のメトリクスを定義します。

histogram, err := meter.SyncFloat64().Histogram("baz", instrument.WithDescription("this is an histogram for visitor tracking"))
if err != nil {
log.Fatal(err)
}
histogram.Record(ctx, 23, attrs...)
histogram.Record(ctx, 7, attrs...)
histogram.Record(ctx, 101, attrs...)
histogram.Record(ctx, 105, attrs...)

ctx, _ = signal.NotifyContext(ctx, os.Interrupt)
<-ctx.Done()

最後に、ルーターとエンドポイントを含むserveMetricsメソッドのロジックは以下の通りです。

func serveMetrics() {
log.Printf("serving metrics at localhost:2223/metrics")
http.Handle("/metrics", promhttp.Handler())
err := http.ListenAndServe(":2223", nil)
if err != nil {
fmt.Printf("error serving http: %v", err)
return
}
}

トレーシング実装

データを生成するための分散トレーシングの設定には、いくつかのコンポーネントの構成が必要です。コードの計装において重要な役割を果たすトレーシングパイプラインのコンポーネントには、以下が含まれます。

• TracerProvider：スパンの生成方法を決定します
• リソースオブジェクト：すべてのスパンのソースを識別します
• SpanProcessor：スパンのエクスポート方法を記述します
• SpanExporter：スパンのエクスポート先を記述します

TracerProviderインターフェースは、トレーサーを取得できるメソッドを作成します。トレーシングには、Jaegerを使用できます。

Jaegerでトレーシングが行われるアプリケーションの例を見てみましょう。まず、以下のライブラリをインポートします。

import (
"context"
"log"
"time"

"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/exporters/jaeger"
"go.opentelemetry.io/otel/sdk/resource"
tracesdk "go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.12.0"
)

Jaegerエクスポーター用に構成されたTracerProviderを返すtraceProvider関数を作成します。エクスポーターは、指定されたURLにスパンを送信します。この関数は、アプリケーションに関するすべての情報を含むリソースを使用するTracerProviderも返します。コードは次のようになります。

func tracerProvider(url string) (*tracesdk.TracerProvider, error)
{
// エクスポーターを作成し、指定されたURLにスパンを送信するよう設定します。 exporter, err :=
jaeger.New(jaeger.WithCollectorEndpoint(jaeger.WithEndpoint(url)
))
if err != nil {
return nil, err
}

// アプリケーションに関する情報を含むリソースを作成します。 trcprov := tracesdk.NewTracerProvider(
// 常にスパンをバッチ処理するエクスポーターを使用します。 tracesdk.WithBatcher(exporter),
// このプロバイダーからのすべてのスパンにリソースを記録します。 tracesdk.WithResource(resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceNameKey.String("trace-demo),
attribute.String("environment", production),
attribute.Int64("ID", 1),
)),
)
return trcprov, nil
}

main関数は、将来インポートされる実装のためにトレーサープロバイダーを登録します。

func main() {
// ... trcprov, err :=
tracerProvider("<http://localhost:14263/api/traces>")
if err != nil {
log.Fatal(err)
}
// このパッケージで使用するグローバルトレーサープロバイダーとして登録します。 otel.SetTracerProvider(trcprov)
// ... }

アプリケーション終了時に、テレメトリーデータをシャットダウンしてシステムからクリーンアップするコードを含めることができます。

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// アプリケーションが終了する前に、トレーサープロバイダーを適切にシャットダウンします。 defer func(ctx context.Context) {
// タイムアウトを超えないようにします。 ctx, cancel = context.WithTimeout(ctx, time.Second*5)
defer cancel()
if err := tp.Shutdown(ctx); err != nil {
log.Fatal(err)
}
}(ctx)

tr := tp.Tracer("component-main")

ctx, span := tr.Start(ctx, "foo")
defer span.End()

この実装には、トレーシングのサポートとスパンの定義が含まれます。 

OpenTelemetry Collector

OpenTelemetryデータの生成は、OpenTelemetryを使用する上で全てではありません。データから最大限に活用することも同様に重要です。テレメトリーデータを送信するための構成済みバックエンドが必要で、ログ、メトリクス、トレース用のパイプラインも必要です。また、必要に応じてバックエンドを簡単に切り替えることができるように、構成済みのサービスも必要です。このセクションでは、OpenTelemetry Collectorについて見ていきます。

テレメトリーデータはアプリケーションからOpenTelemetryに送信されるため、プログラムにはOpenTelemetry Protocol（OTLP）エクスポーターをインストールする必要があります。Goの場合、エクスポーターはこれらのモジュールで利用できます。

go.opentelemetry.io/otel/exporters/otlp/otlptrace
go.opentelemetry.io/otel/exporters/otlp/metric
# GoではOpenTelemetryロギングはまだ実装されていません

JaegerおよびPrometheusエクスポーターは、以下の各モジュールにあります。

go.opentelemetry.io/otel/exporters/jaeger
go.opentelemetry.io/otel/exporters/prometheus

OpenTelemetry Collectorの使用

OpenTelemetry Collectorは、さまざまな形式で、さまざまなサービスからテレメトリーデータを受信します。データを処理し、必要な数の宛先にエクスポートします。

Collectorのデプロイは集中的な作業になる可能性があります。独自にリソースを割いて実行する代わりに、Applications ManagerのようなOTLPをサポートするベンダープラットフォームを活用できます。

OpenTelemetry Collectorをインストールするには、お使いの開発環境の公式ガイドに従ってください。

OpenTelemetry Collectorのコンポーネント

OpenTelemetryのクライアントアーキテクチャで見たように、Collectorはレシーバー、プロセッサー、エクスポーター、パイプラインで構成されています。CollectorはOpenCensusプロジェクトのフォークとして作成され、データの入出力のためにいくつかのオープンソースプロトコルをサポートしています。

Collectorのコンポーネントは、アプリケーションプログラムでComponentインターフェースを実装しており、これにより追加のコンポーネントを追加してCollectorを比較的簡単に拡張できます。

type Component interface {
Start(ctx context.Context, host Host) error
Shutdown(ctx context.Context) error
 

コンポーネントは、パイプラインの一部ではなく、テレメトリーデータへのアクセスを必要としないため、実際のコンポーネントとは見なされない拡張機能やサービスとともに、単一のファイルで構成されます。すべてのコンポーネントの構成例は次のようになります。

receivers:
otlp:
protocols:
grpc:
http:

processors:
batch:

exporters:
otlp:
endpoint: otelcol:4317

extensions:
health_check:
pprof:
zpages:

service:
extensions: [health_check,pprof,zpages]
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlp]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [otlp]
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlp]

以下のセクションでは、これらのコンポーネントについて詳しく説明します。

レシーバー

その名の通り、レシーバーコンポーネントはいくつかのサポートされている形式でデータを受信し、そのデータをOpenTelemetryの内部的に受け入れられるデータ形式に変換します。技術的な意味では、レシーバーはCollector内のポートでプロトコルをリッスンするためのリスナーを定義します。例えば、Jaegerレシーバーは以下のプロトコルをサポートしています。

• Thrift Compact（ポート6831）
• Thrift Binary（ポート6832）
• gRPC（ポート14250）
• Thrift HTTP（ポート14268）

以下の表は、各シグナルタイプでサポートされているレシーバー形式を示しています。