OpenTelemetry Collector internals

© 2025, Amazon Web Services, Inc. or its affiliates. All
rights reserved. 1 © 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved. OpenTelemetry Collector internals Yoshi Yamaguchi (@ymotongpoo) J A P A N C O M M U N I T Y D A Y A T K U B E C O N + C L O U D N A T I V E C O N J A P A N 2 0 2 5 Senior Developer Advocate Amazon Web Services Japan, G.K.

rights reserved. 3 OpenTelemetry meetup

rights reserved. 4 ここにいる全員を OpenTelemetry のコントリビューターにする今⽇の⽬標

rights reserved. 5 Disclaimer 本セッションの解説は以下のソースコードに基づいています • レポジトリ: open-telemetry/opentelemetry-collector • バージョン: v1.34.0 (rev: ab80fb4)

rights reserved. 6 • OpenTelemetry についておさらい • OpenTelemetry Collector の設計のおさらい • OpenTelemetry Collector の内部データモデル • データ変換プロセスアジェンダ

rights reserved. 8 OpenTelemetry についておさらいオブザーバビリティの中でも計装、⽣成、送信に注⼒システム⼊⼒出⼒計装（インスツルメンテーション）送信保存収集可視化

rights reserved. 9 OpenTelemetry のスコープコンポーネント⼊⼒出⼒ API & SDK • OTLP • OTel Arrow Collector

rights reserved. 10 OpenTelemetry のスコープコンポーネント⼊⼒出⼒ API & SDK Collector

rights reserved. 12 3つの主要コンポーネントコンポーネントが独⽴ • Receiver • Processor • Exporter • Connector Receiver Processor Exporter

rights reserved. 13 各コンポーネントの中⾝とその間の通信は︖ Receiver Processor Exporter この中⾝は何してるの︖ ここはどういうデータ型なの︖

rights reserved. 14 各コンポーネントの中⾝とその間の通信は︖ Receiver Processor Exporter ここはどういうデータ型なの︖

rights reserved. 16 事前知識 • OpenTelemetry Collector は Go で実装されている • コアな機能は open-telemetry/opentelemetry-collector にある • OpenTelemetry には標準的なテレメトリー送信プロトコルとして OTLP がある

rights reserved. 17 内部通信も OTLP なのでは︖ pdata は OTLP をラップした上で追加のデータ型を保持している pdata ⽣成された Go コード OTLP Protobuf protoc-gen-gogo pdatagen 例: ptrace type Span struct { // protobuf構造体への直接参照 orig *otlptrace.Span state *internal.State }

rights reserved. 18 pdata: パイプラインデータ型 pdata ptrace pmetric plog pcommon pprofile ※ protobuf から⽣成された型は pdata/internal にあるので pdata 内部からしか触れない

rights reserved. 19 pcommon: パイプライン内共通データ型テンプレートより⾃動⽣成した共通データ型 • 各種プリミティブ型の値 (Value) • 各種プリミティブ型のスライス (FooSlice) • マップ • Timestamp • SpanID、TraceID、TaceState • リソース

rights reserved. 20 ptrace: パイプライン内トレース型 Traces ResourceSpans ScopeSpans Span Status SpanEvent SpanLink 1 n n n n n 1 1 1 1 トレース全体同⼀のリソースからのスパン（例: サービス、ホスト、コンテナ）同⼀のスコープからのスパン（例: ライブラリ、SDK）

rights reserved. 21 ptrace: 簡単なコード例 traces := ptrace.NewTraces() // サービスAのResourceSpans rs := traces.ResourceSpans().AppendEmpty() rs.Resource().Attributes().PutStr("service.name", "service-a") // サービスAのResourceSpansのScopeSpan ss := rs.ScopeSpans().AppendEmpty() scope := scopeSpans.Scope() // InstrumentationScopeの設定 scope.SetName("go.opentelemetry.io/otel/instrumentation/net/http/otelhttp") scope.SetVersion("0.46.0") scope.Attributes().PutStr("instrumentation.type", "automatic")

rights reserved. 22 ptrace: 簡単なコード例 span := scope.Spans().AppendEmpty() span.SetName("HTTP GET /api/users") span.SetKind(ptrace.SpanKindClient) span.SetTraceID(pcommon.TraceID(traceID)) span.SetSpanID(pcommon.SpanID(spanID)) span.SetStartTimestamp(pcommon.NewTimestampFromTime(time.Now())) span.SetEndTimestamp(pcommon.NewTimestampFromTime(time.Now().Add(100*time.M illisecond))) span.Attributes().PutStr("http.method", "GET") span.Attributes().PutStr("http.url", "https://api.example.com/users") span.Attributes().PutInt("http.status_code", 200) span.Status().SetCode(ptrace.StatusCodeOk)

rights reserved. 23 pmetric: パイプライン内メトリクス型 Metrics ResourceMetrics ScopeMetrics 1 n n n 1 1 1 1 1 1 Metric Histogram Gauge Sum HistogramDataPoint NumberDataPoint 1 n n Exemplar 1 1 同⼀のリソースからのメトリクス（例: サービス、ホスト、コンテナ）同⼀のスコープからのメトリクス（例: ライブラリ、SDK）メトリクス（名前、単位、メトリクス種類で定義）トレースとメトリクスの紐づけ n 1 1 メトリクス全体

rights reserved. 24 pmetric: 簡単なコード例 metrics := pmetric.NewMetrics() // サービスAのResourceMetrics rm := metrics.ResourceMetrics().AppendEmpty() rm.Resource().Attributes().PutStr("service.name", "payment-service") // HTTPライブラリからのメトリクス sm := resourceMetrics.ScopeMetrics().AppendEmpty() // スコープの設定 scope := sm.Scope() scope.SetName("go.opentelemetry.io/otel/instrumentation/net/http/otelhttp") scope.SetVersion("0.46.0") scope.Attributes().PutStr("instrumentation.type", "automatic")

rights reserved. 25 pmetric: 簡単なコード例 // HTTP リクエスト数メトリック（Sum） metric := sm.Metrics().AppendEmpty() metric.SetName("http_requests_total") metric.SetDescription("Total number of HTTP requests") metric.SetUnit("1") // Sum タイプとして設定 sum := metric.SetEmptySum() sum.SetIsMonotonic(true) sum.SetAggregationTemporality(pmetric.AggregationTemporalityCumulative)

rights reserved. 26 pmetric: 簡単なコード例 // データポイントを追加 dp := sum.DataPoints().AppendEmpty() now := pcommon.NewTimestampFromTime(time.Now()) dp.SetStartTimestamp(pcommon.NewTimestampFromTime(time.Now().Add(-1*time.Minute))) dp.SetTimestamp(now) dp.SetIntValue(1500) // 1500リクエスト // 属性を設定 dp.Attributes().PutStr("method", "GET") dp.Attributes().PutStr("endpoint", "/api/users") dp.Attributes().PutInt("status_code", 200)

rights reserved. 27 plog: パイプライン内トレース型 Logs ResourceLogs ScopeLogs LogRecord SeverityNumber LogRecordFlag 1 n n n 1 1 1 1 1 ログ全体同⼀のリソースからのログ（例: サービス、ホスト、コンテナ）同⼀のスコープからのログ（例: ライブラリ、SDK）ログ⾏（TraceID、SpanID⽤のフィールドもある）

rights reserved. 28 pprofile: パイプライン内プロファイル型（ベータ） Profiles ResourceProfiles ScopeProfiles Profile 1 n n n 1 1 1 プロファイル全体同⼀のリソースからのプロファイル（例: サービス、ホスト、コンテナ）同⼀のスコープからのプロファイル（例: ライブラリ、SDK）プロファイル Sample Label n n 1 サンプルラベル（ここでTraceIDやSpanIDを相関させる）

rights reserved. 29 コンポーネントは何をしてるの︖ Receiver Processor Exporter この中⾝は何してるの︖

rights reserved. 31 各コンポーネントの実装 • Receiver: 外部テレメトリー形式を pdata に変換 • Processor: pdata を別の pdata に変換 • Exporter: pdata を外部テレメトリー形式に変換 • Connector: パイプライン同⼠の接続 • Extension: Collectorの補助的な機能すべての道は pdata に通じるやったー︕簡単じゃん︕ ...本当に簡単か︖ 今⽇は説明しない

rights reserved. 32 config.yaml receivers: otlp: grpc: processors: batch: memory_limiter: exporters: otlp: endpoint: "your-endpoint:4317" service: pipelines: traces: receivers: [otlp] processors: [memory_limiter, batch] exporters: [otlp]

rights reserved. 33 config.yaml から実際のパイプラインへ config.yaml otlp mem batch otlp 概念上のパイプライン

rights reserved. 34 疑問 1. どうやって config.yaml から各コンポーネントの依存関係を理解しているのか 2. 各コンポーネントはどうやって pdata の送信先を把握しているのか

rights reserved. 35 コンポーネントの依存関係の構築 service/internal/graph/graph.go で有向⾮巡回グラフを作成 1.どうやって config.yaml から各コンポーネントの依存関係を理解しているのか otlp mem batch otlp otlp mem batch otlp 概念上のパイプライン実際のパイプラインこれは何︖

rights reserved. 36 CapabilitiesNode と FanOutNode 最適化のためにパイプラインには仮想的なコンポーネントが存在する • CapabilitiesNode: Receiver が必ず接続するノード • FanOutNode: Processor と Exporter の間に必ず挟まれるノード otlp mem batch otlp CapabilitiesNode FanOutNode

rights reserved. 37 参考: パイプライン⽤構造体の実装 // A node-based representation of a pipeline configuration. type pipelineNodes struct { // Use map to assist with deduplication of connector instances. receivers map[int64]graph.Node // The node to which receivers emit. Passes through to processors. // Easily accessible as the first node in a pipeline. *capabilitiesNode // The order of processors is very important. Therefore use a slice for processors. processors []graph.Node // Emits to exporters. *fanOutNode // Use map to assist with deduplication of connector instances. exporters map[int64]graph.Node }

rights reserved. 38 Consumer 各コンポーネントを実装するとき、次のコンポーネントのことを知らないでも良いように設計されている 2. 各コンポーネントはどうやって pdata の送信先を把握しているのか otlp mem batch otlp otlp 実際のパイプライン Receiver 以外は全部 Consumer

rights reserved. 39 参考: 各コンポーネントの定義（例: トレース） type Traces interface { component.Component } Receiver (receiver/receiver.go) type Traces interface { component.Component consumer.Traces } Processor (processor/processor.go) Exporter (exporter/exporter.go) type Traces interface { component.Component consumer.Traces } type capabilitiesNode struct { …略… baseConsumer consumer.ConsumeTracesFunc …略… } CapabilitiesNode (service/internal/graph/capabilities.go) FanOutNode (service/internal/graph/fanout.go) type fanOutNode struct { …略… baseConsumer } Consumer は ConsumeXXX() を呼べる実装となっている

rights reserved. 40 どうやって Consumer に pdata を渡すのか各コンポーネント内にある nextConsumer の consumer.ConsumeXXX を呼ぶ。これによって次のコンポーネントを知らなくて良くなる。 func CreateTraces( ctx context.Context, set Settings, cfg component.Config, next consumer.Traces ) (Traces, error) Receiver、Processor、Exporter の実装に必要な Factory インターフェイスの CreateXXX メソッドコンポーネントの実装の本体で pdata を渡す next.ConsumeTrace(ctx, traces)

rights reserved. 41 渡された pdata からのデータの取り出し⽅ Factory を実装する際に前のコンポーネントから呼び出される consumer.ConsumeXXXX を実装する必要があり、そこで pdata を直接触れる Processor の場合 Processor ⾃体の ConsumeXXX の実装内で nextConsumer.ConsumeXXX を呼び出して連鎖させる Exporter の場合 Processor ⾃体の ConsumeXXX の実装内で外部データ形式に変換して送信する例: トレース

rights reserved. 42 サンプルコード（概念） func (p *processor) ConsumeTraces(ctx context.Context, td ptrace.Traces) error { newTd := doSomthingWith(td) return next.ConsumeTraces(ctx, newTd) } 前のコンポーネントから呼び出される ConsumeXXX 次のコンポーネントの ConsumeXXX を呼び出す

rights reserved. 43 今⽇話さなかったこと • 各コンポーネントの実際の作り⽅ • コンポーネント作成の規約、Factory の作り⽅ • mdatagen というツールを使います • Extension と Connector • CapabilitiesNode と FanOutNode が何を最適化してるか • Feature Gate https://zenn.dev/ymotongpoo/articles/20231225-metrics-receiver

rights reserved. 44 まとめ • OpenTelemetry Collector 内部ではデータはすべて pdata になってる • 各コンポーネントは Receiver 以外は Consumer として振る舞う • ConsumeXXX のチェーンで pdata を渡している

OpenTelemetry Collector internals

OpenTelemetry Collector internals

More Decks by ymotongpoo

Other Decks in Technology

Featured

Transcript