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

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

Managed ClickStack
ClickStack Open Source

前提条件

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

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

環境変数を設定する

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

export OTLP_AUTH_TOKEN=<your_otlp_auth_token>

認証されていない collectorClickStack 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 "$@"; }

ログを生成する

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

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 はレコード単位の属性を設定します。

トレースを生成する

正常な複数のサービスと、障害が発生している 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 は、より多く、より変化に富んだボリュームを得るために、複数のジェネレーターを並列に実行します。

メトリクスを生成

ダッシュボードでカウンター、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 を指定します。

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) をチャート化し、メトリクスのインジェストを確認します。

前提条件

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

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

環境変数を設定する

インジェスト 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 "$@"; }

ログを生成する

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

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"'

トレースを生成する

正常な複数のサービスと、障害が発生している 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"'

メトリクスを生成する

チャートにカウンター、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 を指定できます。

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) をチャート化して、メトリクスのインジェストを確認します。

​前提条件

​telemetrygen をインストールする

​環境変数を設定する

​ログを生成する

​トレースを生成する

​メトリクスを生成

​ClickStack で確認する

​前提条件

​telemetrygen をインストールする

​環境変数を設定する

​ログを生成する

​トレースを生成する

​メトリクスを生成する

​ClickStack で確認する

前提条件

telemetrygen をインストールする

環境変数を設定する

ログを生成する

トレースを生成する

メトリクスを生成

ClickStack で確認する

前提条件

telemetrygen をインストールする

環境変数を設定する

ログを生成する

トレースを生成する

メトリクスを生成する

ClickStack で確認する