Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

前提条件

このガイドは、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>

各コマンドでは変わる部分 (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) をチャート化し、メトリクスのインジェストを確認します。

Navigation