Share
Embed
仕様と実装で学ぶOpenTelemetry
Pepabo Tech Conference #22 春のSREまつり~ OpenTelemetry活用全て見せます 〜 で発表したスライドです。
https://pepabo.connpass.com/event/314411/
Drumato
May 09, 2024
Transcript
60 slides
-
2 ⾃⼰紹介 技術部 プラットフォームグループ 2024年 中途⼊社 菅原 ⼤和 Yamato Sugawara
• 業務: カラーミーショップのKubernetes運⽤、 OpenTelemetry導⼊を率先、その他 • 好きな分野: ネットワーク/K8s/プログラミング • 趣味: カラオケ/ゲーム/ドラム/技術 • 上から下まで全部⾒たいSRE • とにかくコードも書きたいSRE • X : @drumato -
7 この発表でわかること 1. OpenTelemetry仕様の⼀部にふれることでちょっとだけ詳しくなれます 2. OpenTelemetry Go SDK(の⼀部)を読むことで実装を理解します 2.1. 拡張性のあるGoライブラリ実装パターン
2.2. OpenTelemetry SDKの実装における共通点、API設計 2.3. SDKを使うときの挙動把握 -
8 この発表でわからないこと 1. OpenTelemetryの具体的な活⽤⽅法については扱いません 2. OpenTelemetry SDKの使い⽅については扱いません 3. 時間の都合上、カラーミーショップにおけるOpenTelemetryの取り組み は紹介しません
4. OTLPには触れません 4.1. 次回、詳解OTLP編でお会いしましょう -
OpenTelemetryの仕様 24 OpenTelemetry SDKリーディングで理解するOtel仕様 • OpenTelemetry Go SDKの実装⽚⼿に仕様を理解する • OpenTelemetryの仕様はプログラミング(実装)を強く意識した書き⽅がされている
• 特定の実装に依存しているわけではない • 「OpenTelemetry APIはライブラリ上でかくあるべき」というレベルで具体的 • 注: Go SDKのLogs APIは2024年5⽉現在Alpha -
OpenTelemetryの仕様 25 • OpenTelemetry Specification • OpenTelemetryで扱われるデータ構造や概念の定義、各エコシステムが満た す仕様と実装⽅針まで • OpAMP
• Agentをリモートで設定管理するためのプロトコル定義 • 今回は扱わない • OTLP Specification • シグナルを送受信するプロトコルについて定義 • Semantic Convention • DBやHTTPアプリケーションなど、対象システムが推奨されるルールが定義 OpenTelemetryの仕様概要 -
OpenTelemetryの仕様 26 • OpenTelemetryで扱われるデータ構造や⽤語の定義、それぞれのデータ構造に⾏え る操作を定義した仕様 • Contextとは?Trace IDは何バイト(ビット)?Span Attributeの命名規則は? •
本発表ではOTLPの仕様と区別して呼称 • OTLP Specificationとして、次のスライドで解説 • oteps(OpenTelemetry Enhanced Proposals)で新しい仕様が提案されていたりする OpenTelemetry Specificationとは -
OpenTelemetryの仕様 27 • テレメトリの送受信に⽤いるThe OpenTelemetry Protocol(以下OTLP)の定義 • OTLP/gRPC … Underlying
ProtocolとしてgRPCを使う • gRPC/Protobufを⽤いてメッセージフォーマットを定義 • →定義に従ったメッセージならどのようなプログラムからのメッセージも正常受理される • OTLP/HTTP … Underlying ProtocolとしてHTTP1.1/HTTP2を使う • 上記protobuf定義に対応するJSONをPOSTする • どちらもネットワークレイテンシを考慮して、Concurrent Requestsをサポートする 必要がある(SHOULD) • 本発表では時間の都合上、これ以上は解説しません OTLP Specificationとは -
OpenTelemetry Specification 28 • 以下のパートで構成 • Client Design Principles •
API Specification • SDK Specification • Data Specification • それぞれTracing/Logs/Metricsで分けて定義されている • 今回はTracingだけを扱う OpenTelemetry Specification -
OpenTelemetry Specification 29 • /context … プロセス内のContext伝搬 • /metrics …
Metrics API • /trace … Tracing API • /baggage … • /internal … 公開しない内部実装 • /logs … Logs API Package Layout-API- https://opentelemetry.io/docs/specs/otel/library-layout/ -
OpenTelemetry Specification 32 • OpenTelemetryライブラリが実現しなければならないパフォーマンスとブロッキン グの性質、並⾏制御の挙動について定義 • 例: Tracing APIの場合
• Span/Tracer/TracerProviderのすべてのメソッドはスレッド安全 • Event/Linkはイミュータブルでありスレッド安全なデータ構造 Performance, Blocking, Concurrency, and Thread-Safety https://opentelemetry.io/docs/specs/otel/performance/ https://opentelemetry.io/docs/specs/otel/library-guidelines/#concurrency-and-thread-safety -
OpenTelemetry Specification 34 Client Design Principles https://opentelemetry.io/docs/specs/otel/library-guidelines/#opentelemetry-client-generic-design • フレームワークやライブラリなどはOpenTelemetry APIにのみ依存するようにできる
こと • フレームワークやライブラリを使った最終的な成果物でのみSDKや代替実装を差し込んで利 ⽤できること -
OpenTelemetry Specification 38 • execution unit間や、API境界を横断する情報伝播に⽤いられる • execution unitは、Glossaryにて「スレッドやコルーチン、ファイバーに代表される実⾏単位」と されている
• Contextはimmutableであり、変更APIは「差分適⽤されたContextを返す」べき(MUST) • 以下の操作を持つと定義 • GetValue(key) … コンテキストが内包するkeyに紐づくデータを取得 • SetValue(key, value) … (key, value)という組を内包する新しいコンテキストを初期化し返す • 上記以外にもOptionalとしていくつか操作が定義されている API Specification-Context-1/2 https://opentelemetry.io/docs/specs/otel/context/ -
OpenTelemetry Specification 40 • アプリケーション側で独⾃にテレメトリデータに付加情報をつけるために⽤いられる • 具体的な定義は W3C Baggage Specification
• これ⾃体は分散システムにおけるコンポーネント間のユーザ定義情報を伝搬させるための機能 • OpenTelemetryは仕様上のデータをContextで, それ以外のユーザ定義情報をBaggageで伝搬 API Specification-Baggage- https://opentelemetry.io/docs/specs/otel/baggage/api/ -
OpenTelemetry Specification 41 • 横断的なデータを伝搬するために⽤いる • W3C TraceContextやBaggageをプロセス間で取り回すための便利API、というイメージで良い • それぞれのユースケースごとにInterceptorを⽤意して抽出・挿⼊を⾏う
• 例: HTTPサーバではHTTPリクエストから⽂脈を抽出し、トレースデータに挿⼊する • 現在はTextMapPropagator だけ⽤意しておけば良いということになっている • TextMapPropagator … ⽂字列のキーバリューの組を扱うPropagator オブジェクト • BinaryPropagator というのも提案されている(が今は標準化されていない API Specification-Propagators-1/3 https://opentelemetry.io/docs/specs/otel/context/api-propagators/ -
OpenTelemetry Specification 43 API Specification-Propagators-3/3 https://github.com/open-telemetry/opentelemetry-go/blob/2f662dbe131bb499e63dc99b66605722fcb4d761/propagation/trace_context.go • W3C TraceContextの実装 •
フォーマットに従った⽂字列構築 • その後carrierに書き込む • FlagsSampled については後述 -
OpenTelemetry Specification 44 • PropagatorがContextやBaggageを扱う際にどのようなパス/箱で、伝搬するか/されるか を抽象化したAPI • 例: HTTP経由で伝搬される⽂脈を扱う場合には、HTTPヘッダをCarrierとする API
Specification-Carrier-1/3 https://opentelemetry.io/docs/specs/otel/context/api-propagators/#carrier -
OpenTelemetry Specification 47 API Specification-Tracing- https://opentelemetry.io/docs/specs/otel/trace/api/ • 以下3つで構成 • TracerProvider
… Tracerを構成する設定を持つステートフルオブジェクト • グローバルなProviderを利⽤できるようにすべき(SHOULD) • Tracer … Span⽣成に責任を持つAPI • Tracer以外のAPIでSpan⽣成できるようになっていてはならない(MUST NOT) • Span … トレース内のあるオペレーションを表現する単位 -
OpenTelemetry Specification 50 API Specification-Tracing- https://opentelemetry.io/docs/specs/otel/trace/api/#span • Spanの中⾝ • name
• SpanContext • 親Spanの情報(SpanでもSpanContextでも) • SpanKind(CLIENT/SERVER/PRODUCER/CONSUMER/INTERNAL) • 開始/終了タイムスタンプ • Link(s) • Event(s) • Status -
OpenTelemetry Specification 51 API Specification-Tracing- https://opentelemetry.io/docs/specs/otel/trace/api/#spancontext • Spanのうち、分散トレーシング環境において伝搬する必要のある情報はSpanContextと して別に定義されている •
Contextというワードが混雑してきたので整理 • Context … execution unit間で情報伝播できるようにする普遍的なAPI/データ構造の概念 • W3C TraceContext … W3Cで定義されている、分散トレーシングにおけるトレーシング⽂脈の情 報伝搬に使われるデータフォーマット • Go SDKではPropagatorの実装として存在している • SpanContext … Spanの情報のうち伝搬しなければいけない情報の総称で、W3C TraceContext に準拠している -
OpenTelemetry Specification 52 API Specification-Tracing- https://opentelemetry.io/docs/specs/otel/trace/api/#spancontext • SpanContextの中⾝ • TraceId
… トレースの識別⼦であり、16byte(128bit) • SpanId … 各Spanの識別⼦であり、8byte(64bit) • TraceFlags … トレースごとのフラグ、現在はSampledのみ利⽤されている • TraceState … 独⾃に使われる領域で、W3C TraceContextで定義されている • IsRemote … SpanContextが伝搬されてきたものなのか、ローカルで⽣成されたのか -
OpenTelemetry Specification 56 SDK Specification-Sampling- https://opentelemetry.io/docs/specs/otel/trace/sdk/#sampling • 収集/送信するトレース情報をサンプルすることでオーバーヘッドおよびノイズを軽減す る仕組み •
IsRecording と Sampled という2つの重要なフラグがある • IsRecording … Spanにつけられるフラグで、そのSpanが記録されるべきという意味 • SpanProcessor はIsRecordingがtrueのもののみ対象として処理する • Sampled … SpanContextのTraceFlagsにつけられるフラグ • W3C TraceContextに詳しい定義が書いてある • サンプリングアルゴリズムによって選出されたSpanであることを表す • SpanExporterはSampled Spanを必ず受信する(MUST) • SimpleSpanProcessorにおける対応処理 -
OpenTelemetry Specification 58 SDK Specification-Span Processor- • Spanのstart()/end()にフックして呼び出されるオブジェクトを抽象化したもの • 即時処理するSimpleと、バッチ処理するBatchの実装が存在
• それぞれのProcessorがExporterを内包していて、OTLP経由で送信する • SDKではSpanがTracerを参照し、TracerがTracerProviderを参照し、TracerProviderに Processorが初期化されているので、すべてがSpanから⾒える状態になっている • それぞれはmutex等で排他制御されているので、goroutineで並⾏アクセスしても動く https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-processor -
OpenTelemetry Specification 61 SDK Specification-Span Exporter- • OTLP/HTTPやOTLP/gRPCなど、Span送信に責任を持つコンポーネント • Export/Shutdown/ForceFlushという3つの操作が定義されている(MUST)
• Export … Readable Span(s)を送信する • 無期限にブロックされてはならない(MUST NOT) • Shutdown … SDKのシャットダウンをトリガーに呼び出される • クリーンアップ処理を⾏ったりする • ForceFlush … 送信されていないSpan(s)をすべて送信する • concurrent requestと再送処理の実装はExporterの責務 https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-exporter -
OpenTelemetry Specification 63 SDK Specification-Configuration- • 環境変数でなにが設定できるか等々が定義されている • よくみる OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
とかです https://opentelemetry.io/docs/specs/otel/configuration/ -
OpenTelemetry Specification 65 Data Specification-Semantic Conventions- • Span/Event/Metrics/Logsで対応しておくべき情報が列挙されている • MUSTではなくOptionalだったり、そもそもexperimentalだったりする
• あまりに多いのでここでは紹介しません • open-telemetry/semantic-conventions にすべてが書いてあります • 例1: どのログにも log.record.uid attributeを⼊れて識別できるようにしておく • 例2: DBのSpanには db.query.text attributeに⽣のクエリ⽂字列をいれておく • 例3: HTTPサーバは http.server. response.body.size のHistogram Metricを⼊れておく https://opentelemetry.io/docs/specs/otel/overview/#semantic-conventions -
OpenTelemetryの仕様 70 まとめ • OpenTelemetryは⾼い拡張性と明確な定義を持つ仕様と実装の集合 • ⾃分たちのユースケースに応じて仕組みを作っていくために、根本技術に詳しくなろう • 上記を実現するためにSDKはよく考えられた設計が採⽤されている •
ソフトウェアアーキテクチャのケーススタディとして勉強になる • ミニマルなサブセットを作るのはそこまで難しくない • 仕様が明確なので、それにしたがって作っていけば良い • 公式がサポートしていない⾔語を使っているなら、作ってしまうのも良いかも -
OpenTelemetryの仕様 71 参考資料 • OpenTelemetry Specification • OTLP Specification •
https://github.com/open-telemetry/opentelemetry-go