🕌

OpenTelemetry のカスタムビルドを試す

2024/06/14に公開

OpenTelemetry

tech

この記事を読むと

OpenTelemetry Collector のカスタムビルドについて知ることができます

最初に

OpenTelemetry Collector（以下、Otel Collector または Collector）を使ったアプリケーションのトレース、メトリクス収集では、設定次第で様々なバックエンドに送信することが可能です。
また、Processor によるフィルタリング、バッチ処理などのデータ処理を行うことも可能であり、より拡張性の高いデータ収集を行うことが可能となります。

触っていく中で、設定ファイルをいじって色々と試したくなります。
そんな時、OpenTelemetry Collector Builder (ocb) によるカスタムビルドが役に立ちましたので、この記事ではOpenTelemetry Collector Builder (ocb) の紹介をします。

OpenTelemetry Collector Builder (ocb) とは

カスタマイズした OpenTelemetry Collector のバイナリファイルを作成できるツールです。

カスタムビルドを試す

1. インストール

公式docs ではこちらで紹介されています。

各自の環境に合わせてバイナリをダウンロードします。

当方の環境は MacbookPro(Intel Core i5)であるため、[MacOS(AMMD64)] によるコマンドを実行します。

$ uname -m
x86_64

$ curl --proto '=https' --tlsv1.2 -fL -o ocb \
$ https://github.com/open-telemetry/opentelemetry-collector/releases/download/cmd%2Fbuilder%2Fv0.102.1/ocb_0.102.1_darwin_amd64
$ chmod +x ocb

ocb というバイナリファイルが作成されます。

2. ビルド用の manifest ファイルの作成

これから作成されるカスタム Collector ディストリビューションに追加したいコンポーネントを記述します。
manifest ファイルは、dist から始まる yaml 形式で記載します。
今回は公式 docs にあるように以下のコンポーネントを追加してみます。

Exporters: OTLP and Debug
Receivers: OTLP
Processors: Batch

builder-config.yaml

dist:
  name: otelcol-dev //作成されるディストリビューションにつける名前
  description: Basic OTel Collector distribution for Developers
  output_path: ./otelcol-dev //作成されるディストリビューションのバイナリファイルの作成パス
  otelcol_version: 0.102.1

exporters:
  - gomod:
      go.opentelemetry.io/collector/exporter/debugexporter v0.102.1
  - gomod:
      go.opentelemetry.io/collector/exporter/otlpexporter v0.102.1

processors:
  - gomod:
      go.opentelemetry.io/collector/processor/batchprocessor v0.102.1

receivers:
  - gomod:
      go.opentelemetry.io/collector/receiver/otlpreceiver v0.102.1

3. ビルド実行

ステップ2で作成した manifest ファイルを指定して、ocb を実行します。

$ ./ocb --config builder-config.yaml

2024-06-14T08:58:19.903+0900    INFO    internal/command.go:125 OpenTelemetry Collector Builder {"version": "0.102.1", "date": "2024-06-05T15:02:33Z"}
2024-06-14T08:58:19.904+0900    INFO    internal/command.go:161 Using config file       {"path": "builder-config.yaml"}
2024-06-14T08:58:19.906+0900    INFO    builder/config.go:132   Using go        {"go-executable": "/usr/local/bin/go"}
2024-06-14T08:58:19.908+0900    INFO    builder/main.go:100     Sources created {"path": "./otelcol-dev"}
2024-06-14T08:58:30.943+0900    INFO    builder/main.go:191     Getting go modules
2024-06-14T08:58:47.196+0900    INFO    builder/main.go:111     Compiling
2024-06-14T08:59:01.374+0900    INFO    builder/main.go:130     Compiled        {"binary": "./otelcol-dev/otelcol-dev"}

manifest ファイルで指定したパスotelcol-dev が作成され、独自の Collector ディストリビューションが展開されます。

$ tree
.
├── builder-config.yaml
├── ocb
└── otelcol-dev
    ├── components.go
    ├── go.mod
    ├── go.sum
    ├── main.go
    ├── main_others.go
    ├── main_windows.go
    └── otelcol-dev

作成されたカスタム Collector を動かす

ここまでで、カスタム Collector となる otelcol-dev が作成されました。
バイナリファイル otelcol-dev を実行しますと、OpenTelemetry Collector が動作します。

続いて、通常の Otel Collector を動かすときのように、設定ファイルを作成して動かしてみます。

上述のように、今回は以下のコンポーネントを追加しました。
そのため、これらのコンポーネントが使用できます。

Exporters: OTLP and Debug
Receivers: OTLP
Processors: Batch

完成系イメージ

最終的にはこのような構成になります。

以下、図にある①〜③それぞれの設定を見ていきます。

① トレースを出力するアプリケーションの準備

トレースを出力するアプリケーションが必要となりますが、手軽に Telemetry データを出力できるアプリケーションTelemetry generator for OpenTelemetryを使用します。

デフォルトでは、port:4317 を使用して Telemetry データを出力します。

$ go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
($GOBIN が設定されていると、$GOBIN に実行ファイルが保存されるかと思います)

$ telemetrygen -h 
Telemetrygen simulates a client generating traces, metrics, and logs

Usage:
  telemetrygen [command]

Examples:
telemetrygen traces
telemetrygen metrics
telemetrygen logs

Available Commands:
  help        Help about any command
  logs        Simulates a client generating logs. (Stability level: Development)
  metrics     Simulates a client generating metrics. (Stability level: Development)
  traces      Simulates a client generating traces. (Stability level: Alpha)

Flags:
  -h, --help   help for telemetrygen

② トレースデータを可視化するバックエンドの準備

otlpexporter を使用していることもあり、Jaeger を使って可視化させてみます。
ローカル上で実行していることもあり、コンテナで Jaeger を起動します。

$ docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 14317:4317 \
  -p 14318:4318 \
  jaegertracing/all-in-one:1.41

http://localhost:16686 へアクセスすると、Jaeger UI を確認できます。

③ Otel Collector の設定

Otel Collector の設定ファイルを作成します。

$ cd otelcol-dev
$ touch config.yaml

config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:

exporters:
  debug:
    verbosity: detailed
  otlp/jaeger:
    endpoint: localhost:14317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/jaeger, debug]
  telemetry:
    logs:
      level: debug

debug について、コンソール上でログを確認する場合などは必要です。

Otel Collector 起動

設定ファイルを指定して、Collector を起動します。

$ ./otelcol-dev --config=config.yaml
2024-06-14T14:18:58.009+0900    info    service@v0.102.1/service.go:113 Setting up own telemetry...
2024-06-14T14:18:58.012+0900    info    service@v0.102.1/telemetry.go:96        Serving metrics {"address": ":8888", "level": "Normal"}
2024-06-14T14:18:58.012+0900    debug   exporter@v0.102.1/exporter.go:273       Stable component.       {"kind": "exporter", "data_type": "traces", "name": "otlp/jaeger"}
2024-06-14T14:18:58.013+0900    debug   processor@v0.102.1/processor.go:301     Beta component. May change in the future.     {"kind": "processor", "name": "batch", "pipeline": "traces"}
2024-06-14T14:18:58.014+0900    debug   receiver@v0.102.1/receiver.go:308       Stable component.       {"kind": "receiver", "name": "otlp", "data_type": "traces"}
2024-06-14T14:18:58.015+0900    info    service@v0.102.1/service.go:180 Starting otelcol-dev... {"Version": "1.0.0", "NumCPU": 8}
2024-06-14T14:18:58.015+0900    info    extensions/extensions.go:34     Starting extensions...
...

追加したコンポーネント以外を指定すると、エラーとなります。
例：

config.yaml

exporters:
  prometheus: //追加していないコンポーネント
    endpoint: "1.2.3.4:1234"

 $ ./otelcol-dev --config=config.yaml
Error: failed to get config: cannot unmarshal the configuration: 1 error(s) decoding:

* error decoding 'exporters': unknown type: "prometheus" for id: "prometheus" (valid values: [debug otlp])
2024/06/14 09:06:49 collector server run finished with error: failed to get config: cannot unmarshal the configuration: 1 error(s) decoding:

トレースデータの作成

telemetrygen を使ってトレースデータを出力します。

$ telemetrygen traces --otlp-insecure --traces 1

2024-06-14T14:08:58.215+0900    INFO    traces/traces.go:52     starting gRPC exporter
2024-06-14T14:08:58.215+0900    INFO    grpc@v1.64.0/clientconn.go:431  [core][Channel #1]Channel created       {"system": "grpc", "grpc_log": true}
2024-06-14T14:08:58.215+0900    INFO    grpc@v1.64.0/clientconn.go:1684 [core][Channel #1]original dial target is: "localhost:4317" {"system": "grpc", "grpc_log": true}
2024-06-14T14:08:58.215+0900    INFO    grpc@v1.64.0/clientconn.go:1691 [core][Channel #1]parsed dial target is: resolver.Target{URL:url.URL{Scheme:"localhost", Opaque:"4317", User:(*url.Userinfo)(nil), Host:"", Path:"", RawPath:"", OmitHost:false, ForceQuery:false, RawQuery:"", Fragment:"", RawFragment:""}}   {"system": "grpc", "grpc_log": true}
..

Jaeger 確認

http://localhost:16686 にアクセスしてみましょう。

トレースデータが出力されていることを確認しました🥳

最後に

カスタムビルドをすることで、自身の環境に合わせたコンポーネントをインストールして Collector を作成できることがわかりました。
「このExporter,Processor ってどうやって使うのだろう？」「Receiver 自作したい！」などを試すにはちょうど良いかもしれません。
また、ソースコードも自動で作成されることで、ソースコードベースでどのように処理が行われているのか？を調査するにも有用かと思います。

ほんとは、Collector の処理がどのような流れなのかを把握したくてコードを読んでいたもののいまいち流れを追えず、このカスタムビルドに行き当たりました。
次はそれぞれの処理がどう行われているのか、ソースコードを読んでいきたいと思います。