telemetrygen で合成 OpenTelemetry データを生成する

telemetrygen を使用して、多様な合成ログ、トレース、メトリクスを ClickStack OpenTelemetry collector に送信します

telemetrygen は、OpenTelemetry Collector Contrib のデータ生成ツールです。合成 OTLP ログ、トレース、メトリクスを生成し、データの内容を調整できる各種フラグを備えています。たとえば、複数のサービス、ログの重大度、span の status や子 span、さまざまなメトリクスタイプを指定できます。これを使うことで、ClickStack OpenTelemetry collector がデータを受け付けていることや、多様で現実的なイベントが ClickStack UI に表示されることを確認できます。

このガイドでは、collector がすでに稼働しており、4317 (gRPC) と 4318 (HTTP) で OTLP エンドポイントを公開していることを前提としています。

Managed ClickStack

1. 前提条件

   このガイドは、Managed ClickStack の Getting Started Guide を完了しており、telemetrygen を実行するマシンから OTLP gRPC (4317) および HTTP (4318) のエンドポイントにアクセスできる OpenTelemetry collector が稼働していることを前提としています。collector を OTLP_AUTH_TOKEN で保護 している場合は、その値をすぐ使えるようにしておいてください。

2. telemetrygen をインストールする

   Dockerイメージから telemetrygen を実行します (インストールは不要です) 。以降のコマンドを見やすくするために、簡単なラッパーを定義します。--add-host を使うと、コンテナーからホスト上で待ち受けている collector に接続できます。

   telemetrygen() {
     docker run --rm --add-host=host.docker.internal:host-gateway \
       ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest "$@"
   }
   export OTEL_ENDPOINT=host.docker.internal:4317
   

   または、Go でバイナリをインストールし、代わりに localhost を対象にします。

   go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
   export OTEL_ENDPOINT=localhost:4317
   
3. 環境変数を設定する

   collector が保護されている場合は、認証トークンを設定します。

   export OTLP_AUTH_TOKEN=<your_otlp_auth_token>
   

   認証されていない collector

   ClickStack OpenTelemetry collector はデフォルトで認証されていません。OTLP_AUTH_TOKEN を設定するために collector の保護 の手順を実施していない場合は、以下のヘルパーから --otlp-header の行を削除してください。

   各コマンドでは変わる部分 (service、severity、status、属性) だけを指定すればよいように、小さな tg ヘルパーを定義します:

   tg() { local signal=$1; shift; telemetrygen "$signal" \
     --otlp-endpoint ${OTEL_ENDPOINT} --otlp-insecure \
     --otlp-header "authorization=\"${OTLP_AUTH_TOKEN}\"" \
     --rate 5 --duration 30s "$@"; }
   
4. ログを生成する

   ログは、単一で均一なストリームではなく、複数のサービスにまたがって、主に情報レベルを中心に警告やエラーも含めた現実的な重大度の組み合わせで送信します。

   tg logs --service frontend --severity-text Info  --severity-number 9  --body "GET /api/products 200" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="GET"' --telemetry-attributes 'http.status_code="200"'
   tg logs --service checkout --severity-text Warn  --severity-number 13 --body "retrying payment authorization" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="POST"'
   tg logs --service payment  --severity-text Error --severity-number 17 --body "payment gateway timeout" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.status_code="500"'
   

   特に便利なログフラグ:

   • --service は service.name を設定し、イベントをサービスに紐付けられるようにします。
   • --severity-text と --severity-number はレベルを設定します (severity-number は 1 ～ 24 の範囲です) 。
   • --body はログメッセージを設定します。
   • --otlp-attributes はリソースレベルの属性を設定します (key="value"、key=true、または key=<integer>) 。
   • --telemetry-attributes はレコード単位の属性を設定します。
5. トレースを生成する

   正常な複数のサービスと、障害が発生している 1 つの依存先から、複数のスパンを含むトレースを送信します。これにより、サービスマップは大半が正常で 1 つのサービスのみがエラーを返す、より現実的な構成となり、エラービューにもデータが投入されます。

   # Healthy services: the bulk of the traffic, all spans Ok
   for svc in frontend checkout cart; do
     tg traces --service "$svc" --child-spans 3 --span-duration 80ms --status-code Ok \
       --otlp-attributes 'deployment.environment="production"' \
       --telemetry-attributes "http.route=\"/$svc\""
   done
   
   # One slow dependency returning errors
   tg traces --service payment --child-spans 3 --span-duration 450ms --span-links 1 --status-code Error \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.route="/charge"'
   

   特に便利な trace フラグ:

   • --child-spans は、trace ごとに指定した数の子 span を生成し、各 trace に実際の深さを持たせます。
   • --span-duration は、各 span の継続時間を設定します (例: 120ms、2s) 。
   • --status-code は、Unset、Error、Ok (または 0、1、2) のいずれかです。エラービューを試すには Error を使用します。
   • --span-links は、span 間にリンクを追加します。
   • --workers は、より多く、より変化に富んだボリュームを得るために、複数のジェネレーターを並列に実行します。
6. メトリクスを生成

   ダッシュボードでカウンター、Gauge、分布を利用できるよう、一般的な3種類のメトリクスタイプを送信します。一部のジェネレーターとは異なり、telemetrygen はメトリクスでも --duration を尊重するため、手動で停止する必要はありません。

   tg metrics --service frontend --metric-type Sum       --otlp-metric-name http.server.requests --aggregation-temporality cumulative
   tg metrics --service frontend --metric-type Gauge     --otlp-metric-name system.memory.usage
   tg metrics --service payment  --metric-type Histogram --otlp-metric-name http.server.duration
   

   --metric-type には Gauge、Sum、Histogram、または ExponentialHistogram を指定できます。--otlp-metric-name は series 名を指定するオプションで、UI で見つけやすくなります。--aggregation-temporality には delta または cumulative を指定します。

7. ClickStack で確認する

   ClickHouse Cloud コンソールから ClickStack UI を開きます。Search ビューで、時間範囲を Last 15 minutes に設定し、ログソースを Logs と Traces に切り替えます。ServiceName で絞り込んで frontend、checkout、cart、payment の各サービスを表示し、SeverityText で絞り込んで warning と error のログ行を探します。payment の trace を開き、子 span とエラーステータスを確認します。Chart Explorer を開き、Metrics を選択して、上で設定したメトリクス名の 1 つ (たとえば http.server.requests) をチャート化し、メトリクスのインジェストを確認します。

ClickStack Open Source

1. 前提条件

   このガイドでは、all-in-one イメージの手順に従って Open Source ClickStack を起動しており、OTLP エンドポイント (4317 gRPC および 4318 HTTP) に接続できることを前提としています。また、Team Settings > API Keys にある HyperDX UI のインジェスト API key も必要です。

2. telemetrygen をインストールする

   Dockerイメージから telemetrygen を実行します (インストールは不要です) 。以下のコマンドを読みやすくするため、簡単なラッパーを定義します。--add-host を指定すると、コンテナーからホスト上で待ち受けている collector に接続できます。

   telemetrygen() {
     docker run --rm --add-host=host.docker.internal:host-gateway \
       ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest "$@"
   }
   export OTEL_ENDPOINT=host.docker.internal:4317
   

   または、Go を使ってバイナリをインストールし、代わりに localhost を指定します。

   go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
   export OTEL_ENDPOINT=localhost:4317
   
3. 環境変数を設定する

   インジェスト API key をエクスポートします。

   export CLICKSTACK_API_KEY=<your_ingestion_api_key>
   

   各コマンドで変わる部分 (service、severity、status、属性) だけを指定すればよいよう、簡単な tg ヘルパーを定義します:

   tg() { local signal=$1; shift; telemetrygen "$signal" \
     --otlp-endpoint ${OTEL_ENDPOINT} --otlp-insecure \
     --otlp-header "authorization=\"${CLICKSTACK_API_KEY}\"" \
     --rate 5 --duration 30s "$@"; }
   
4. ログを生成する

   サービス全体で重大度が現実的に混在するようにログを送信します。大半は情報レベルとし、均一な単一ストリームではなく、警告やエラーも含めます。

   tg logs --service frontend --severity-text Info  --severity-number 9  --body "GET /api/products 200" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="GET"' --telemetry-attributes 'http.status_code="200"'
   tg logs --service checkout --severity-text Warn  --severity-number 13 --body "retrying payment authorization" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.method="POST"'
   tg logs --service payment  --severity-text Error --severity-number 17 --body "payment gateway timeout" \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.status_code="500"'
   
5. トレースを生成する

   正常な複数のサービスと、障害が発生している 1 つの依存先から、複数のスパンを含むトレースを送信します。これにより、サービスマップには現実的な構成 (大半は正常で、1 つのサービスでエラーが発生している状態) が反映され、エラービューにもデータが表示されます。

   # Healthy services: the bulk of the traffic, all spans Ok
   for svc in frontend checkout cart; do
     tg traces --service "$svc" --child-spans 3 --span-duration 80ms --status-code Ok \
       --otlp-attributes 'deployment.environment="production"' \
       --telemetry-attributes "http.route=\"/$svc\""
   done
   
   # One slow dependency returning errors
   tg traces --service payment --child-spans 3 --span-duration 450ms --span-links 1 --status-code Error \
     --otlp-attributes 'deployment.environment="production"' \
     --telemetry-attributes 'http.route="/charge"'
   
6. メトリクスを生成する

   チャートにカウンター、Gauge、分布を表示できるように、一般的な 3 種類のメトリクスを送信します。

   tg metrics --service frontend --metric-type Sum       --otlp-metric-name http.server.requests --aggregation-temporality cumulative
   tg metrics --service frontend --metric-type Gauge     --otlp-metric-name system.memory.usage
   tg metrics --service payment  --metric-type Histogram --otlp-metric-name http.server.duration
   

   --metric-type には Gauge、Sum、Histogram、または ExponentialHistogram を指定できます。

7. ClickStack で確認する

   http://localhost:8080 にアクセスして ClickStack UI を開きます。Search ビューで、時間範囲を Last 15 minutes に設定し、ログソースを Logs と Traces の間で切り替えます。ServiceName で絞り込むと frontend、checkout、cart、payment の各サービスを確認でき、SeverityText で絞り込むと warning と error のログ行を見つけられます。payment のトレースを開き、子スパンとエラーのステータスを確認します。Chart Explorer を開いて Metrics を選択し、先ほど設定したメトリクス名の 1 つ (たとえば http.server.requests) をチャート化して、メトリクスのインジェストを確認します。