仕様と実装で学ぶOpenTelemetry

Pepabo Tech Conference #22 春のSREまつり~ OpenTelemetry活用全て見せます 〜 で発表したスライドです。

https://pepabo.connpass.com/event/314411/

Transcript

1. 1 仕様と実装で学ぶ OpenTelemetry Drumato/菅原 ⼤和 技術部プラットフォームグループ 2024.5.9
2. 2 ⾃⼰紹介 技術部 プラットフォームグループ 2024年 中途⼊社 菅原 ⼤和 Yamato Sugawara • 業務: カラーミーショップのKubernetes運⽤、 OpenTelemetry導⼊を率先、その他 • 好きな分野: ネットワーク/K8s/プログラミング • 趣味: カラオケ/ゲーム/ドラム/技術 • 上から下まで全部⾒たいSRE • とにかくコードも書きたいSRE • X : @drumato
3. 3 アジェンダ 1. Go SDKと合わせて理解するOpenTelemetryの仕様(いけるとこまで) 2. Zigで作るSDKミニマルサブセット
4. 4 OpenTelemetry, 使ってますか?
5. 5 OpenTelemetryの Specificationを読んだことは ありますか?
6. 6 OpenTelemetryの SDK実装を読んだことは ありますか?
7. 7 この発表でわかること 1. OpenTelemetry仕様の⼀部にふれることでちょっとだけ詳しくなれます 2. OpenTelemetry Go SDK(の⼀部)を読むことで実装を理解します 2.1. 拡張性のあるGoライブラリ実装パターン 2.2. OpenTelemetry SDKの実装における共通点、API設計 2.3. SDKを使うときの挙動把握
8. 8 この発表でわからないこと 1. OpenTelemetryの具体的な活⽤⽅法については扱いません 2. OpenTelemetry SDKの使い⽅については扱いません 3. 時間の都合上、カラーミーショップにおけるOpenTelemetryの取り組み は紹介しません 4. OTLPには触れません 4.1. 次回、詳解OTLP編でお会いしましょう
9. 3. OpenTelemetryの仕様 21
10. 仕様をひたすらに読むのはつらい 22
11. ｢実装｣も合わせて理解しよう 23
12. OpenTelemetryの仕様 24 OpenTelemetry SDKリーディングで理解するOtel仕様 • OpenTelemetry Go SDKの実装⽚⼿に仕様を理解する • OpenTelemetryの仕様はプログラミング(実装)を強く意識した書き⽅がされている • 特定の実装に依存しているわけではない • ｢OpenTelemetry APIはライブラリ上でかくあるべき｣というレベルで具体的 • 注: Go SDKのLogs APIは2024年5⽉現在Alpha
13. OpenTelemetryの仕様 25 • OpenTelemetry Specification • OpenTelemetryで扱われるデータ構造や概念の定義、各エコシステムが満た す仕様と実装⽅針まで • OpAMP • Agentをリモートで設定管理するためのプロトコル定義 • 今回は扱わない • OTLP Specification • シグナルを送受信するプロトコルについて定義 • Semantic Convention • DBやHTTPアプリケーションなど、対象システムが推奨されるルールが定義 OpenTelemetryの仕様概要
14. OpenTelemetryの仕様 26 • OpenTelemetryで扱われるデータ構造や⽤語の定義、それぞれのデータ構造に⾏え る操作を定義した仕様 • Contextとは?Trace IDは何バイト(ビット)?Span Attributeの命名規則は? • 本発表ではOTLPの仕様と区別して呼称 • OTLP Specificationとして、次のスライドで解説 • oteps(OpenTelemetry Enhanced Proposals)で新しい仕様が提案されていたりする OpenTelemetry Specificationとは
15. 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とは
16. OpenTelemetry Specification 28 • 以下のパートで構成 • Client Design Principles • API Specification • SDK Specification • Data Specification • それぞれTracing/Logs/Metricsで分けて定義されている • 今回はTracingだけを扱う OpenTelemetry Specification
17. 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/
18. OpenTelemetry Specification 30 Package Layout-API- https://github.com/open-telemetry/opentelemetry-go
19. OpenTelemetry Specification 31 Package Layout-API- https://github.com/open-telemetry/opentelemetry-go Goではプロセス内伝搬に context.Contextを⽤いるため /contextはない
20. 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
21. 3-1. Client Design Principles 33
22. OpenTelemetry Specification 34 Client Design Principles https://opentelemetry.io/docs/specs/otel/library-guidelines/#opentelemetry-client-generic-design • フレームワークやライブラリなどはOpenTelemetry APIにのみ依存するようにできる こと • フレームワークやライブラリを使った最終的な成果物でのみSDKや代替実装を差し込んで利 ⽤できること
23. OpenTelemetry Specification 35 Client Design Principles https://opentelemetry.io/docs/specs/otel/library-guidelines/#opentelemetry-client-generic-design
24. OpenTelemetry Specification 36 Client Design Principles APIとSDKが 分かれている https://opentelemetry.io/docs/specs/otel/library-guidelines/#opentelemetry-client-generic-design
25. 3-2. API Specification 37
26. 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/
27. OpenTelemetry Specification 39 • Goのcontextパッケージは先述した要件をそのまま満たす標準パッケージ API Specification-Context-2/2 https://pkg.go.dev/context
28. OpenTelemetry Specification 40 • アプリケーション側で独⾃にテレメトリデータに付加情報をつけるために⽤いられる • 具体的な定義は W3C Baggage Specification • これ⾃体は分散システムにおけるコンポーネント間のユーザ定義情報を伝搬させるための機能 • OpenTelemetryは仕様上のデータをContextで, それ以外のユーザ定義情報をBaggageで伝搬 API Specification-Baggage- https://opentelemetry.io/docs/specs/otel/baggage/api/
29. 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/
30. OpenTelemetry Specification 42 API Specification-Propagators-2/3 https://pkg.go.dev/go.opentelemetry.io/otel@v1.26.0/propagation#TextMapPropagator
31. 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 については後述
32. 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
33. OpenTelemetry Specification 45 API Specification-Carrier-2/3 https://pkg.go.dev/go.opentelemetry.io/otel@v1.26.0/propagation
34. OpenTelemetry Specification 46 API Specification-Carrier-3/3 https://github.com/open-telemetry/opentelemetry-go/blob/2f662dbe131bb499e63dc99b66605722fcb4d761/propagation/propagation.go • シンプルな実装
35. 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 … トレース内のあるオペレーションを表現する単位
36. OpenTelemetry Specification 48 API Specification-Tracing- https://pkg.go.dev/go.opentelemetry.io/otel/trace
37. OpenTelemetry Specification 49 API Specification-Tracing- https://pkg.go.dev/go.opentelemetry.io/otel/trace
38. 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
39. 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 に準拠している
40. 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が伝搬されてきたものなのか、ローカルで⽣成されたのか
41. OpenTelemetry Specification 53 API Specification-Tracing- https://opentelemetry.io/docs/specs/otel/trace/api/#add-link • Spanは別のSpanContextとLinkを結べるようになっていなければならない(MUST) • Linkは異なるトレース間のSpanContextでも結べるようになっている
42. 3-3. SDK Specification 54
43. OpenTelemetry Specification 55 SDK Specification-Tracing- https://opentelemetry.io/docs/specs/otel/trace/sdk/ • ⾮常に⼤きいので、いくつかピックアップして紹介
44. 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における対応処理
45. OpenTelemetry Specification 57 SDK Specification-ID Generator- https://github.com/open-telemetry/opentelemetry-go/blob/2f662dbe131bb499e63dc99b66605722fcb4d761/sdk/trace/id_generator.go#L16-L35
46. 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
47. OpenTelemetry Specification 59 SDK Specification-Span Processor- https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-processor
48. OpenTelemetry Specification 60 SDK Specification-Span Processor- https://github.com/open-telemetry/opentelemetry-go/blob/main/sdk/trace/simple_span_processor.go#L44C1-L54C2
49. 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
50. OpenTelemetry Specification 62 SDK Specification-Span Exporter- https://github.com/open-telemetry/opentelemetry-go/blob/main/exporters/otlp/otlptrace/exporter.go
51. OpenTelemetry Specification 63 SDK Specification-Configuration- • 環境変数でなにが設定できるか等々が定義されている • よくみる OTEL_EXPORTER_OTLP_TRACES_ENDPOINT とかです https://opentelemetry.io/docs/specs/otel/configuration/
52. 3-4. Data Specification 64
53. 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
54. 4. Zigでつくる SDKミニマルサブセット 66
55. 完成品 67 https://github.com/Drumato/opentelemetry-zig
56. ZigでつくるSDKミニマルサブセット 68 デモ
57. ZigでつくるSDKミニマルサブセット 69 デモ
58. OpenTelemetryの仕様 70 まとめ • OpenTelemetryは⾼い拡張性と明確な定義を持つ仕様と実装の集合 • ⾃分たちのユースケースに応じて仕組みを作っていくために、根本技術に詳しくなろう • 上記を実現するためにSDKはよく考えられた設計が採⽤されている • ソフトウェアアーキテクチャのケーススタディとして勉強になる • ミニマルなサブセットを作るのはそこまで難しくない • 仕様が明確なので、それにしたがって作っていけば良い • 公式がサポートしていない⾔語を使っているなら、作ってしまうのも良いかも
59. OpenTelemetryの仕様 71 参考資料 • OpenTelemetry Specification • OTLP Specification • https://github.com/open-telemetry/opentelemetry-go
60. 72 We’re hiring! OpenTelemetryだけでなく、ペパボのSREに興味がある⽅