1. Agent 設定の確認

15 minutes

ようこそ！このセクションでは、Agent と Gateway の両方を含む完全に機能する OpenTelemetry セットアップから始めます。

まず、設定ファイルを簡単に確認して、全体的な構造に慣れ、テレメトリーパイプラインを制御する重要なセクションを確認します。

Tip

ワークショップを通じて、複数のターミナルウィンドウを使用します。整理しやすくするために、各ターミナルに固有の名前または色を付けてください。これにより、演習中にターミナルを簡単に識別して切り替えることができます。

これらのターミナルを Agent、Gateway、Loadgen、Test と呼びます。

Exercise

最初のターミナルウィンドウを作成し、Agent と名前を付けます。最初の演習用ディレクトリ [WORKSHOP]/1-agent-gateway に移動し、必要なファイルが生成されていることを確認します
```
cd 1-agent-gateway
ls -l
```
ディレクトリに以下のファイルが表示されるはずです。表示されない場合は、前提条件 セクションで説明されている setup-workshop.sh スクリプトを再実行してください
. ├── agent.yaml └── gateway.yaml

Agent 設定の理解

このワークショップで使用する agent.yaml ファイルの主要なコンポーネントを確認しましょう。メトリクス、トレース、ログをサポートするために重要な追加が行われています。

Receiver

receivers セクションは、Agent がテレメトリーデータを取り込む方法を定義します。このセットアップでは、3種類の Receiver が設定されています

Host Metrics Receiver

hostmetrics:                         # Host Metrics Receiver
  collection_interval: 3600s         # Collection Interval (1hr)
  scrapers:
    cpu:                             # CPU Scraper

ローカルシステムから1時間ごとに CPU 使用率を収集します。これを使用してサンプルメトリクスデータを生成します。

OTLP Receiver（HTTP プロトコル）

otlp:                                # OTLP Receiver
  protocols:
    http:                            # Configure HTTP protocol
      endpoint: "0.0.0.0:4318"       # Endpoint to bind to

Agent がポート 4318 で HTTP 経由でメトリクス、トレース、ログを受信できるようにします。これは、今後の演習で Collector にデータを送信するために使用されます。

FileLog Receiver

filelog/quotes:                      # Receiver Type/Name
  include: ./quotes.log              # The file to read log data from
  include_file_path: true            # Include file path in the log data
  include_file_name: false           # Exclude file name from the log data
  resource:                          # Add custom resource attributes
    com.splunk.source: ./quotes.log  # Source of the log data
    com.splunk.sourcetype: quotes    # Source type of the log data

Agent がローカルログファイル（quotes.log）を tail し、source や sourceType などのメタデータで強化された構造化ログイベントに変換できるようにします。

Exporter

Debug Exporter

  debug:                               # Exporter Type
    verbosity: detailed                # Enabled detailed debug output

OTLPHTTP Exporter
```
  otlphttp:                            # Exporter Type
    endpoint: "http://localhost:5318"  # Gateway OTLP endpoint
```
debug Exporter はワークショップ中の可視性とデバッグのためにデータをコンソールに送信し、otlphttp Exporter はすべてのテレメトリーをローカルの Gateway インスタンスに転送します。
このデュアルエクスポート戦略により、生データをローカルで確認しながら、さらなる処理とエクスポートのためにダウンストリームに送信することができます。

1.1 Gateway 設定の確認

OpenTelemetry Gateway は、テレメトリーデータの受信、処理、エクスポートのための中央ハブとして機能します。テレメトリーソース（アプリケーションやサービスなど）と Splunk Observability Cloud のようなオブザーバビリティバックエンドの間に位置します。

テレメトリートラフィックを集中化することで、Gateway はデータのフィルタリング、エンリッチメント、変換、および1つ以上の宛先へのルーティングなどの高度な機能を実現します。個々のサービスからテレメトリー処理をオフロードすることで負担を軽減し、分散システム全体で一貫した標準化されたデータを確保します。

これにより、オブザーバビリティパイプラインの管理、スケーリング、分析が容易になります。特に複雑なマルチサービス環境では効果的です。

Exercise

2つ目のターミナルウィンドウを開くか作成し、Gateway と名前を付けます。最初の演習ディレクトリ [WORKSHOP]/1-agent-gateway に移動し、gateway.yaml ファイルの内容を確認します。

このファイルは、Gateway モードでデプロイされた OpenTelemetry Collector のコア構造を示しています。

Gateway 設定の理解

このワークショップで Gateway モードの OpenTelemetry Collector がどのように設定されているかを定義する gateway.yaml ファイルを確認しましょう。この Gateway は、Agent からテレメトリーを受信し、処理してから検査または転送のためにエクスポートする役割を担います。

OTLP Receiver（カスタムポート）
```
receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:5318"
```
ポート 5318 は Agent 設定の otlphttp Exporter と一致しており、Agent が送信するすべてのテレメトリーデータが Gateway で受け入れられることを保証します。

メモ

このポートの分離により、競合を回避し、Agent と Gateway の役割間の責任を明確に保ちます。

File Exporter

Gateway は3つの File Exporter を使用して、テレメトリーデータをローカルファイルに出力します。これらの Exporter は以下のように定義されています

exporters:                        # List of exporters
  debug:                          # Debug exporter
    verbosity: detailed           # Enable detailed debug output
  file/traces:                    # Exporter Type/Name
    path: "./gateway-traces.out"  # Path for OTLP JSON output for traces
    append: false                 # Overwrite the file each time
  file/metrics:                   # Exporter Type/Name
    path: "./gateway-metrics.out" # Path for OTLP JSON output for metrics
    append: false                 # Overwrite the file each time
  file/logs:                      # Exporter Type/Name
    path: "./gateway-logs.out"    # Path for OTLP JSON output for logs
    append: false                 # Overwrite the file each time

各 Exporter は、特定のシグナルタイプを対応するファイルに書き込みます。

これらのファイルは Gateway が起動すると作成され、Agent がデータを送信すると実際のテレメトリーが書き込まれます。これらのファイルをリアルタイムで監視して、パイプラインを通過するテレメトリーの流れを観察できます。

1.2 設定の検証とテスト

次に、Gateway と Agent を起動します。Agent は起動時に自動的に Host Metrics を送信するよう設定されています。これにより、データが Agent から Gateway に正しくルーティングされることを確認します。

Exercise

Gateway: Gateway ターミナル ウィンドウで、以下のコマンドを実行して Gateway を起動します

../otelcol --config=gateway.yaml

すべてが正しく設定されている場合、Collector が起動し、出力に Everything is ready. Begin running and processing data. と表示されます。以下のような出力になります

2025-06-09T09:22:11.944+0100    info    service@v0.126.0/service.go:289 Everything is ready. Begin running and processing data. {"resource": {}}

Gateway が実行されると、ポート 5318 で受信データをリッスンし、受信したデータを以下のファイルにエクスポートします

gateway-traces.out
gateway-metrics.out
gateway-logs.out

Agent の起動: Agent ターミナル ウィンドウで、Agent 設定を使用して Agent を起動します

../otelcol --config=agent.yaml

CPU メトリクスの確認:

Agent が起動すると、すぐに CPU メトリクスの送信を開始することを確認します。
Agent と Gateway の両方がデバッグ出力にこのアクティビティを表示します。出力は以下のスニペットのようになります

<snip>
NumberDataPoints #31
Data point attributes:
     -> cpu: Str(cpu3)
     -> state: Str(wait)
StartTimestamp: 2025-07-07 16:49:42 +0000 UTC
Timestamp: 2025-07-09 09:36:21.190226459 +0000 UTC
Value: 77.380000
        {"resource": {}, "otelcol.component.id": "debug", "otelcol.component.kind": "exporter", "otelcol.signal": "metrics"}

この段階で、Agent は1時間ごとまたは再起動ごとに CPU メトリクスを収集し、Gateway に送信し続けます。Gateway はこれらのメトリクスを処理し、gateway-metrics.out という名前のファイルにエクスポートします。このファイルは、パイプラインサービスの一部としてエクスポートされたメトリクスを保存します。

Gateway にデータが到着したことの確認: CPU メトリクス（特に cpu0）が Gateway に正常に到達したことを確認するために、jq コマンドを使用して gateway-metrics.out ファイルを検査します。

以下のコマンドは、system.cpu.time メトリクスをフィルタリングして抽出し、cpu0 に焦点を当てます。メトリクスの状態（例：user、system、idle、interrupt）と対応する値を表示します。

3つ目のターミナルウィンドウを開くか作成し、Tests と名前を付けます。Tests ターミナル で以下のコマンドを実行して system.cpu.time メトリクスを確認します

jq '.resourceMetrics[].scopeMetrics[].metrics[] | select(.name == "system.cpu.time") | .sum.dataPoints[] | select(.attributes[0].value.stringValue == "cpu0") | {cpu: .attributes[0].value.stringValue, state: .attributes[1].value.stringValue, value: .asDouble}' gateway-metrics.out

{
  "cpu": "cpu0",
  "state": "user",
  "value": 123407.02
}
{
  "cpu": "cpu0",
  "state": "system",
  "value": 64866.6
}
{
  "cpu": "cpu0",
  "state": "idle",
  "value": 216427.87
}
{
  "cpu": "cpu0",
  "state": "interrupt",
  "value": 0
}

重要

Agent と Gateway のプロセスを、それぞれのターミナルで Ctrl-C を押して停止してください。

1. Agent 設定の確認

Agent 設定の理解

Receiver

Exporter

1. Agent Configurationのサブセクション

1.1 Gateway 設定の確認

Gateway 設定の理解

1.2 設定の検証とテスト