OpenTelemetryコレクター設定のカスタマイズ

20 minutes

デフォルト設定を使用して K8s クラスターに Splunk Distribution of OpenTelemetry コレクターをデプロイしました。このセクションでは、コレクター設定をカスタマイズする方法をいくつかの例で説明します。

コレクター設定の取得

コレクター設定をカスタマイズする前に、現在の設定がどのようになっているかをどのように確認するのでしょうか？

Kubernetes 環境では、コレクター設定は Config Map を使用して保存されます。

以下のコマンドで、クラスターに存在する config map を確認できます：

kubectl get cm -l app=splunk-otel-collector

NAME                                                 DATA   AGE
splunk-otel-collector-otel-k8s-cluster-receiver   1      3h37m
splunk-otel-collector-otel-agent                  1      3h37m

なぜ 2 つの config map があるのでしょうか？

次に、以下のようにコレクターエージェントの config map を表示できます：

kubectl describe cm splunk-otel-collector-otel-agent

Name:         splunk-otel-collector-otel-agent
Namespace:    default
Labels:       app=splunk-otel-collector
              app.kubernetes.io/instance=splunk-otel-collector
              app.kubernetes.io/managed-by=Helm
              app.kubernetes.io/name=splunk-otel-collector
              app.kubernetes.io/version=0.113.0
              chart=splunk-otel-collector-0.113.0
              helm.sh/chart=splunk-otel-collector-0.113.0
              heritage=Helm
              release=splunk-otel-collector
Annotations:  meta.helm.sh/release-name: splunk-otel-collector
              meta.helm.sh/release-namespace: default

Data
====
relay:
----
exporters:
  otlphttp:
    headers:
      X-SF-Token: ${SPLUNK_OBSERVABILITY_ACCESS_TOKEN}
    metrics_endpoint: https://ingest.us1.signalfx.com/v2/datapoint/otlp
    traces_endpoint: https://ingest.us1.signalfx.com/v2/trace/otlp
    (followed by the rest of the collector config in yaml format)

K8s でコレクター設定を更新する方法

Linux インスタンスでコレクターを実行した以前の例では、コレクター設定は /etc/otel/collector/agent_config.yamlファイルで利用可能でした。その場合にコレクター設定を変更する必要があれば、単純にこのファイルを編集し、変更を保存してからコレクターを再起動すればよかったのです。

K8s では、少し異なる動作をします。agent_config.yamlを直接変更する代わりに、 helm チャートをデプロイするために使用されるvalues.yamlファイルを変更することでコレクター設定をカスタマイズします。

GitHubの values.yaml ファイルには、利用可能なカスタマイズオプションが記載されています。

例を見てみましょう。

Infrastructure Events Monitoring の追加

最初の例として、K8s クラスターの infrastructure events monitoring を有効にしましょう。

これにより、charts の Events Feed セクションの一部として Kubernetes イベントを確認できるようになります。 cluster receiver は、kubernetes-events monitor を使用して Smart Agent receiver で設定され、custom イベントを送信します。詳細についてはCollect Kubernetes eventsを参照してください。

これはvalues.yamlファイルに以下の行を追加することで実行されます：

ヒント：vi での開き方と保存方法は前のステップにあります。

logsEngine: otel
splunkObservability:
  infrastructureMonitoringEventsEnabled: true
agent:

ファイルが保存されたら、以下のコマンドで変更を適用できます：

helm upgrade splunk-otel-collector \
  --set="splunkObservability.realm=$REALM" \
  --set="splunkObservability.accessToken=$ACCESS_TOKEN" \
  --set="clusterName=$INSTANCE-cluster" \
  --set="environment=otel-$INSTANCE" \
  --set="splunkPlatform.token=$HEC_TOKEN" \
  --set="splunkPlatform.endpoint=$HEC_URL" \
  --set="splunkPlatform.index=splunk4rookies-workshop" \
  -f values.yaml \
splunk-otel-collector-chart/splunk-otel-collector

Release "splunk-otel-collector" has been upgraded. Happy Helming!
NAME: splunk-otel-collector
LAST DEPLOYED: Fri Dec 20 01:17:03 2024
NAMESPACE: default
STATUS: deployed
REVISION: 2
TEST SUITE: None
NOTES:
Splunk OpenTelemetry Collector is installed and configured to send data to Splunk Observability realm us1.

その後、config map を表示して変更が適用されたことを確認できます：

kubectl describe cm splunk-otel-collector-otel-k8s-cluster-receiver

smartagent/kubernetes-eventsが agent config に含まれていることを確認してください：

  smartagent/kubernetes-events:
    alwaysClusterReporter: true
    type: kubernetes-events
    whitelistedEvents:
    - involvedObjectKind: Pod
      reason: Created
    - involvedObjectKind: Pod
      reason: Unhealthy
    - involvedObjectKind: Pod
      reason: Failed
    - involvedObjectKind: Job
      reason: FailedCreate

これらの特定の変更が適用されるのは cluster receiver config map なので、そちらを指定していることに注意してください。

Debug Exporter の追加

collector に送信される trace と log を確認して、 Splunk に送信する前に検査したいとします。この目的のために debug exporter を使用できます。これは OpenTelemetry 関連の問題のトラブルシューティングに役立ちます。

values.yaml ファイルの下部に以下のように debug exporter を追加しましょう：

logsEngine: otel
splunkObservability:
  infrastructureMonitoringEventsEnabled: true
agent:
  config:
    receivers: ...
    exporters:
      debug:
        verbosity: detailed
    service:
      pipelines:
        traces:
          exporters:
            - debug
        logs:
          exporters:
            - debug

ファイルが保存されたら、以下のコマンドで変更を適用できます：

helm upgrade splunk-otel-collector \
  --set="splunkObservability.realm=$REALM" \
  --set="splunkObservability.accessToken=$ACCESS_TOKEN" \
  --set="clusterName=$INSTANCE-cluster" \
  --set="environment=otel-$INSTANCE" \
  --set="splunkPlatform.token=$HEC_TOKEN" \
  --set="splunkPlatform.endpoint=$HEC_URL" \
  --set="splunkPlatform.index=splunk4rookies-workshop" \
  -f values.yaml \
splunk-otel-collector-chart/splunk-otel-collector

Release "splunk-otel-collector" has been upgraded. Happy Helming!
NAME: splunk-otel-collector
LAST DEPLOYED: Fri Dec 20 01:32:03 2024
NAMESPACE: default
STATUS: deployed
REVISION: 3
TEST SUITE: None
NOTES:
Splunk OpenTelemetry Collector is installed and configured to send data to Splunk Observability realm us1.

curl を使用してアプリケーションを数回実行してから、以下のコマンドで agent collector の log を tail します：

kubectl logs -l component=otel-collector-agent -f

以下のような trace が agent collector の log に書き込まれているのが確認できるはずです：

2024-12-20T01:43:52.929Z info Traces {"kind": "exporter", "data_type": "traces", "name": "debug", "resource spans": 1, "spans": 2}
2024-12-20T01:43:52.929Z info ResourceSpans #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.6.1
Resource attributes:
     -> splunk.distro.version: Str(1.8.0)
     -> telemetry.distro.name: Str(splunk-otel-dotnet)
     -> telemetry.distro.version: Str(1.8.0)
     -> os.type: Str(linux)
     -> os.description: Str(Debian GNU/Linux 12 (bookworm))
     -> os.build_id: Str(6.8.0-1021-aws)
     -> os.name: Str(Debian GNU/Linux)
     -> os.version: Str(12)
     -> host.name: Str(derek-1)
     -> process.owner: Str(app)
     -> process.pid: Int(1)
     -> process.runtime.description: Str(.NET 8.0.11)
     -> process.runtime.name: Str(.NET)
     -> process.runtime.version: Str(8.0.11)
     -> container.id: Str(78b452a43bbaa3354a3cb474010efd6ae2367165a1356f4b4000be031b10c5aa)
     -> telemetry.sdk.name: Str(opentelemetry)
     -> telemetry.sdk.language: Str(dotnet)
     -> telemetry.sdk.version: Str(1.9.0)
     -> service.name: Str(helloworld)
     -> deployment.environment: Str(otel-derek-1)
     -> k8s.pod.ip: Str(10.42.0.15)
     -> k8s.pod.labels.app: Str(helloworld)
     -> k8s.pod.name: Str(helloworld-84865965d9-nkqsx)
     -> k8s.namespace.name: Str(default)
     -> k8s.pod.uid: Str(38d39bc6-1309-4022-a569-8acceef50942)
     -> k8s.node.name: Str(derek-1)
     -> k8s.cluster.name: Str(derek-1-cluster)

そして以下のような log エントリも確認できます：

2024-12-20T01:43:53.215Z info Logs {"kind": "exporter", "data_type": "logs", "name": "debug", "resource logs": 1, "log records": 2}
2024-12-20T01:43:53.215Z info ResourceLog #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.6.1
Resource attributes:
     -> splunk.distro.version: Str(1.8.0)
     -> telemetry.distro.name: Str(splunk-otel-dotnet)
     -> telemetry.distro.version: Str(1.8.0)
     -> os.type: Str(linux)
     -> os.description: Str(Debian GNU/Linux 12 (bookworm))
     -> os.build_id: Str(6.8.0-1021-aws)
     -> os.name: Str(Debian GNU/Linux)
     -> os.version: Str(12)
     -> host.name: Str(derek-1)
     -> process.owner: Str(app)
     -> process.pid: Int(1)
     -> process.runtime.description: Str(.NET 8.0.11)
     -> process.runtime.name: Str(.NET)
     -> process.runtime.version: Str(8.0.11)
     -> container.id: Str(78b452a43bbaa3354a3cb474010efd6ae2367165a1356f4b4000be031b10c5aa)
     -> telemetry.sdk.name: Str(opentelemetry)
     -> telemetry.sdk.language: Str(dotnet)
     -> telemetry.sdk.version: Str(1.9.0)
     -> service.name: Str(helloworld)
     -> deployment.environment: Str(otel-derek-1)
     -> k8s.node.name: Str(derek-1)
     -> k8s.cluster.name: Str(derek-1-cluster)

ただし、Splunk Observability Cloud に戻ると、アプリケーションから trace と log がもはやそこに送信されていないことに気づくでしょう。

なぜそうなったと思いますか？次のセクションで詳しく説明します。