OpenTelemetry でオブザーバビリティをクラウドネイティブに

1 hour Author Robert Castley

概要

OpenTelemetry を始めたばかりの組織では、まずオブザーバビリティバックエンドに直接データを送信することから始めることが多いでしょう。これは初期テストには有効ですが、OpenTelemetry Collector をオブザーバビリティアーキテクチャの一部として使用することで多くのメリットがあり、本番環境へのデプロイには推奨されています。

このワークショップでは、OpenTelemetry Collector の使用に焦点を当て、Splunk Observability Cloud で使用するための Receiver、Processor、Exporter の設定の基本から始めます。参加者は初心者から、分散プラットフォームのビジネスオブザーバビリティニーズを解決するためのカスタムコンポーネントを追加できるレベルまで到達します。

Ninja セクション

ワークショップを通じて、展開可能な Ninja セクションがあります。これらはより実践的で、ワークショップ中または自分の時間に探求できる詳細な技術情報を提供します。

OpenTelemetry プロジェクトは頻繁に開発が行われているため、これらのセクションの内容が古くなる可能性があることに注意してください。詳細が同期していない場合はリンクが提供されます。更新が必要な箇所を見つけた場合はお知らせください。

Ninja: テストしてみよう！

このワークショップを完了すると、正式に OpenTelemetry Collector Ninja になれます！

対象者

このインタラクティブなワークショップは、OpenTelemetry Collector のアーキテクチャとデプロイについて詳しく学びたい開発者およびシステム管理者を対象としています。

前提条件

データ収集の基本的な理解があること
コマンドラインと vim/vi の経験があること
Ubuntu 20.04 LTS または 22.04 LTS を実行しているインスタンス/ホスト/VM があること
- 最小要件は AWS/EC2 t2.micro（1 CPU、1GB RAM、8GB ストレージ）です

学習目標

このワークショップを終えると、参加者は以下ができるようになります

OpenTelemetry のコンポーネントを理解する
Receiver、Processor、Exporter を使用してデータを収集・分析する
OpenTelemetry を使用するメリットを理解する
ビジネスニーズを解決するカスタムコンポーネントを構築する

OpenTelemetry アーキテクチャ

%%{
  init:{
    "theme":"base",
    "themeVariables": {
      "primaryColor": "#ffffff",
      "clusterBkg": "#eff2fb",
      "defaultLinkColor": "#333333"
    }
  }
}%%

flowchart LR;
    subgraph Collector
    A[OTLP] --> M(Receivers)
    B[JAEGER] --> M(Receivers)
    C[Prometheus] --> M(Receivers)
    end
    subgraph Processors
    M(Receivers) --> H(Filters, Attributes, etc)
    E(Extensions)
    end
    subgraph Exporters
    H(Filters, Attributes, etc) --> S(OTLP)
    H(Filters, Attributes, etc) --> T(JAEGER)
    H(Filters, Attributes, etc) --> U(Prometheus)
    end

OpenTelemetry Collector Contrib のインストール

OpenTelemetry Collector Contrib ディストリビューションのダウンロード

OpenTelemetry Collector をインストールする最初のステップは、ダウンロードです。このラボでは、wget コマンドを使用して OpenTelemetry の GitHub リポジトリから .deb パッケージをダウンロードします。

お使いのプラットフォーム用の .deb パッケージを OpenTelemetry Collector Contrib リリースページ から取得します。

wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.111.0/otelcol-contrib_0.111.0_linux_amd64.deb

OpenTelemetry Collector Contrib ディストリビューションのインストール

dpkg を使用して .deb パッケージをインストールします。インストールが成功した場合の出力例は、下の dpkg Output タブを確認してください

sudo dpkg -i otelcol-contrib_0.111.0_linux_amd64.deb

Selecting previously unselected package otelcol-contrib.
(Reading database ... 89232 files and directories currently installed.)
Preparing to unpack otelcol-contrib_0.111.0_linux_amd64.deb ...
Unpacking otelcol-contrib (0.111.0) ...
Setting up otelcol-contrib (0.111.0) ...
Created symlink /etc/systemd/system/multi-user.target.wants/otelcol-contrib.service → /lib/systemd/system/otelcol-contrib.service.

OpenTelemetry Collector Contrib のインストール

Collector が動作していることを確認する

Collector が動作しているはずです。systemctl コマンドを使用して root として確認します。ステータス表示を終了するには q を押してください。

sudo systemctl status otelcol-contrib

● otelcol-contrib.service - OpenTelemetry Collector Contrib
     Loaded: loaded (/lib/systemd/system/otelcol-contrib.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2024-10-07 10:27:49 BST; 52s ago
   Main PID: 17113 (otelcol-contrib)
      Tasks: 13 (limit: 19238)
     Memory: 34.8M
        CPU: 155ms
     CGroup: /system.slice/otelcol-contrib.service
             └─17113 /usr/bin/otelcol-contrib --config=/etc/otelcol-contrib/config.yaml

Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]: Descriptor:
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]:      -> Name: up
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]:      -> Description: The scraping was successful
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]:      -> Unit:
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]:      -> DataType: Gauge
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]: NumberDataPoints #0
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]: StartTimestamp: 1970-01-01 00:00:00 +0000 UTC
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]: Timestamp: 2024-10-07 09:28:36.942 +0000 UTC
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]: Value: 1.000000
Oct 07 10:28:36 petclinic-rum-testing otelcol-contrib[17113]:         {"kind": "exporter", "data_type": "metrics", "name": "debug"}

このワークショップでは、設定ファイルの変更、環境変数の設定、Collector の再起動を複数回行うため、Collector サービスを停止し、起動時の自動起動を無効にする必要があります。

sudo systemctl stop otelcol-contrib && sudo systemctl disable otelcol-contrib

Ninja: Open Telemetry Collector Builder (ocb) を使用して独自の Collector をビルドする

このパートでは、システムに以下がインストールされている必要があります

Golang（最新バージョン）

cd /tmp
wget https://golang.org/dl/go1.20.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.20.linux-amd64.tar.gz

.profile を編集して、以下の環境変数を追加します

export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$GOPATH/bin:$GOROOT/bin:$PATH

シェルセッションを更新します

source ~/.profile

Go のバージョンを確認します

go version

ocb のインストール
- プロジェクトリリースから ocb バイナリをダウンロードし、以下のコマンドを実行します
```
mv ocb_0.80.0_darwin_arm64 /usr/bin/ocb
chmod 755 /usr/bin/ocb
```
  別の方法として、golang ツールチェーンを使用してローカルでバイナリをビルドすることもできます
```
go install go.opentelemetry.io/collector/cmd/builder@v0.80.0
mv $(go env GOPATH)/bin/builder /usr/bin/ocb
```
（オプション）Docker

なぜ独自の Collector をビルドするのか？

Collector のデフォルトディストリビューション（core と contrib）は、提供する機能が多すぎるか少なすぎるかのどちらかです。

また、contrib Collector を本番環境で実行することは推奨されません。これは、インストールされるコンポーネントの量が多く、そのほとんどがデプロイメントに必要ないためです。

独自の Collector をビルドするメリットは？

独自の Collector バイナリ（一般的にディストリビューションと呼ばれる）を作成することは、必要なものだけをビルドすることを意味します。

これには以下のメリットがあります

より小さなサイズのバイナリ
脆弱性に対して既存の Go スキャナーを使用できる
組織と連携できる内部コンポーネントを含めることができる

Collector をビルドする際の考慮事項は？

さて、いくつかのデメリットがなければ 🥷 Ninja ゾーンとは言えません

Go の経験が推奨される（必須ではないが）
Splunk サポートなし
ディストリビューションとライフサイクル管理の責任

プロジェクトは安定性に向けて取り組んでいますが、変更によってワークフローが壊れないとは限らないことに注意することが重要です。Splunk のチームは、より高いサポートと安定性を提供しており、デプロイメントのニーズに応じたキュレーションされた体験を提供できます。

Ninja ゾーン

必要なツールがすべてインストールされたら、otelcol-builder.yaml という名前の新しいファイルを作成し、以下のディレクトリ構造に従います

.
└── otelcol-builder.yaml

ファイルを作成したら、いくつかの追加メタデータとともにインストールするコンポーネントのリストを追加する必要があります。

この例では、入門用の設定に必要なコンポーネントのみをインストールするビルダーマニフェストを作成します

dist:
  name: otelcol-ninja
  description: A custom build of the Open Telemetry Collector
  output_path: ./dist

extensions:
- gomod: go.opentelemetry.io/collector/extension/ballastextension v0.80.0
- gomod: go.opentelemetry.io/collector/extension/zpagesextension  v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/httpforwarder v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.80.0

exporters:
- gomod: go.opentelemetry.io/collector/exporter/loggingexporter v0.80.0
- gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/splunkhecexporter v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/signalfxexporter v0.80.0

processors:
- gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.80.0
- gomod: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.80.0

receivers:
- gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jaegerreceiver v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/prometheusreceiver v0.80.0
- gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/zipkinreceiver v0.80.0

yaml ファイルが ocb 用に更新されたら、以下のコマンドを実行します

ocb --config=otelcol-builder.yaml

これにより、以下のディレクトリ構造が作成されます

├── dist
│   ├── components.go
│   ├── components_test.go
│   ├── go.mod
│   ├── go.sum
│   ├── main.go
│   ├── main_others.go
│   ├── main_windows.go
│   └── otelcol-ninja
└── otelcol-builder.yaml

参考資料

https://opentelemetry.io/docs/collector/custom-collector/

デフォルト設定

OpenTelemetry は YAML ファイルを通じて設定されます。これらのファイルには、ニーズに合わせて変更できるデフォルト設定があります。提供されるデフォルト設定を見てみましょう

cat /etc/otelcol-contrib/config.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# To limit exposure to denial of service attacks, change the host in endpoints below from 0.0.0.0 to a specific network interface.
# See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md#safeguards-against-denial-of-service-attacks

extensions:
  health_check:
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  opencensus:
    endpoint: 0.0.0.0:55678

  # Collect own metrics
  prometheus:
    config:
      scrape_configs:
      - job_name: 'otel-collector'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
      thrift_binary:
        endpoint: 0.0.0.0:6832
      thrift_compact:
        endpoint: 0.0.0.0:6831
      thrift_http:
        endpoint: 0.0.0.0:14268

  zipkin:
    endpoint: 0.0.0.0:9411

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [otlp, opencensus, prometheus]
      processors: [batch]
      exporters: [debug]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

  extensions: [health_check, pprof, zpages]

おめでとうございます！OpenTelemetry Collector のダウンロードとインストールに成功しました。OTel Ninja への道を順調に歩んでいます。しかしまず、設定ファイルと OpenTelemetry Collector の異なるディストリビューションについて説明していきましょう。

メモ

Splunk は独自の、完全にサポートされた OpenTelemetry Collector ディストリビューションを提供しています。このディストリビューションは、Splunk GitHub リポジトリからインストールするか、Splunk Observability Cloud のウィザードを使用してコピー＆ペーストするだけの簡単なインストールスクリプトを作成できます。このディストリビューションには、OpenTelemetry Collector Contrib ディストリビューションでは利用できない多くの追加機能と拡張が含まれています。

Splunk Distribution of the OpenTelemetry Collector は本番環境でテスト済みです。大多数のお客様が本番環境で使用しています。
このディストリビューションを使用するお客様は、SLA 内で Splunk の公式サポートから直接サポートを受けることができます。
お客様は、メトリクスとトレース収集のコア設定体験に対する将来の破壊的変更を心配することなく、Splunk Distribution of the OpenTelemetry Collector を使用または移行できます（OpenTelemetry ログ収集の設定はベータ版です）。Collector のメトリクスには破壊的変更がある可能性があります。

これから設定ファイルの各セクションを説明し、ホストメトリクスを Splunk Observability Cloud に送信するように変更していきます。

OpenTelemetry Collector Extensions

OpenTelemetry Collector がインストールできたので、OpenTelemetry Collector の拡張機能について見ていきましょう。拡張機能はオプションであり、主にテレメトリデータの処理を伴わないタスクに使用されます。拡張機能の例としては、ヘルスモニタリング、サービスディスカバリ、データ転送などがあります。

%%{
  init:{
    "theme": "base",
    "themeVariables": {
      "primaryColor": "#ffffff",
      "clusterBkg": "#eff2fb",
      "defaultLinkColor": "#333333"
    }
  }
}%%

flowchart LR;
    style E fill:#e20082,stroke:#333,stroke-width:4px,color:#fff
    subgraph Collector
    A[OTLP] --> M(Receivers)
    B[JAEGER] --> M(Receivers)
    C[Prometheus] --> M(Receivers)
    end
    subgraph Processors
    M(Receivers) --> H(Filters, Attributes, etc)
    E(Extensions)
    end
    subgraph Exporters
    H(Filters, Attributes, etc) --> S(OTLP)
    H(Filters, Attributes, etc) --> T(JAEGER)
    H(Filters, Attributes, etc) --> U(Prometheus)
    end

OpenTelemetry Collector Extensions

Health Check

拡張機能は、インストール手順で参照した同じ config.yaml ファイルで設定します。config.yaml ファイルを編集して拡張機能を設定しましょう。pprof と zpages 拡張機能はデフォルトの config.yaml ファイルに既に設定されていることに注意してください。このワークショップでは、Collector のヘルス状態にアクセスできるよう、すべてのネットワークインターフェースでポートを公開するように health_check 拡張機能のみを更新します。

sudo vi /etc/otelcol-contrib/config.yaml

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

Collector を起動します

otelcol-contrib --config=file:/etc/otelcol-contrib/config.yaml

この拡張機能により、OpenTelemetry Collector のステータスを確認するためにプローブできる HTTP URL が有効になります。この拡張機能は、Kubernetes で liveness プローブや readiness プローブとして使用できます。curl コマンドについて詳しく知るには、curl man page を確認してください。

新しいターミナルセッションを開き、インスタンスに SSH 接続して以下のコマンドを実行します

curl http://localhost:13133

{"status":"Server available","upSince":"2024-10-07T11:00:08.004685295+01:00","uptime":"12.56420005s"}

OpenTelemetry Collector Extensions

Performance Profiler

Performance Profiler 拡張機能は、golang の net/http/pprof エンドポイントを有効にします。これは通常、開発者がパフォーマンスプロファイルを収集し、サービスの問題を調査するために使用されます。このワークショップではこれを扱いません。

OpenTelemetry Collector Extensions

zPages

zPages は、外部エクスポーターの代わりにインプロセスで使用できる機能です。組み込まれると、バックグラウンドでトレースとメトリクス情報を収集・集約し、リクエストされたときにウェブページでこのデータを提供します。zPages は、Collector が期待どおりに動作していることを確認するための非常に便利な診断機能です。

ServiceZ は、Collector サービスの概要と、pipelinez、extensionz、featurez の各 zPages へのクイックアクセスを提供します。このページには、ビルド情報とランタイム情報も表示されます。

サンプル URL: http://localhost:55679/debug/servicez（localhost をご自身の環境に合わせて変更してください）。

PipelineZ は、Collector で実行されているパイプラインに関する洞察を提供します。タイプ、データが変更されるかどうかの情報を確認でき、各パイプラインで使用されているレシーバー、プロセッサー、エクスポーターの情報も確認できます。

サンプル URL: http://localhost:55679/debug/pipelinez（localhost をご自身の環境に合わせて変更してください）。

ExtensionZ は、Collector でアクティブな拡張機能を表示します。

サンプル URL: http://localhost:55679/debug/extensionz（localhost をご自身の環境に合わせて変更してください）。

Ninja: storage 拡張機能でデータの耐久性を向上させる

このためには、使用しているディストリビューションに file_storage 拡張機能がインストールされていることを確認する必要があります。これは、otelcol-contrib components コマンドを実行することで確認でき、以下のような結果が表示されるはずです

# ... truncated for clarity
extensions:
  - file_storage

buildinfo:
    command: otelcol-contrib
    description: OpenTelemetry Collector Contrib
    version: 0.80.0
receivers:
    - prometheus_simple
    - apache
    - influxdb
    - purefa
    - purefb
    - receiver_creator
    - mongodbatlas
    - vcenter
    - snmp
    - expvar
    - jmx
    - kafka
    - skywalking
    - udplog
    - carbon
    - kafkametrics
    - memcached
    - prometheus
    - windowseventlog
    - zookeeper
    - otlp
    - awsecscontainermetrics
    - iis
    - mysql
    - nsxt
    - aerospike
    - elasticsearch
    - httpcheck
    - k8sobjects
    - mongodb
    - hostmetrics
    - signalfx
    - statsd
    - awsxray
    - cloudfoundry
    - collectd
    - couchdb
    - kubeletstats
    - jaeger
    - journald
    - riak
    - splunk_hec
    - active_directory_ds
    - awscloudwatch
    - sqlquery
    - windowsperfcounters
    - flinkmetrics
    - googlecloudpubsub
    - podman_stats
    - wavefront
    - k8s_events
    - postgresql
    - rabbitmq
    - sapm
    - sqlserver
    - redis
    - solace
    - tcplog
    - awscontainerinsightreceiver
    - awsfirehose
    - bigip
    - filelog
    - googlecloudspanner
    - cloudflare
    - docker_stats
    - k8s_cluster
    - pulsar
    - zipkin
    - nginx
    - opencensus
    - azureeventhub
    - datadog
    - fluentforward
    - otlpjsonfile
    - syslog
processors:
    - resource
    - batch
    - cumulativetodelta
    - groupbyattrs
    - groupbytrace
    - k8sattributes
    - experimental_metricsgeneration
    - metricstransform
    - routing
    - attributes
    - datadog
    - deltatorate
    - spanmetrics
    - span
    - memory_limiter
    - redaction
    - resourcedetection
    - servicegraph
    - transform
    - filter
    - probabilistic_sampler
    - tail_sampling
exporters:
    - otlp
    - carbon
    - datadog
    - f5cloud
    - kafka
    - mezmo
    - skywalking
    - awsxray
    - dynatrace
    - loki
    - prometheus
    - logging
    - azuredataexplorer
    - azuremonitor
    - instana
    - jaeger
    - loadbalancing
    - sentry
    - splunk_hec
    - tanzuobservability
    - zipkin
    - alibabacloud_logservice
    - clickhouse
    - file
    - googlecloud
    - prometheusremotewrite
    - awscloudwatchlogs
    - googlecloudpubsub
    - jaeger_thrift
    - logzio
    - sapm
    - sumologic
    - otlphttp
    - googlemanagedprometheus
    - opencensus
    - awskinesis
    - coralogix
    - influxdb
    - logicmonitor
    - signalfx
    - tencentcloud_logservice
    - awsemf
    - elasticsearch
    - pulsar
extensions:
    - zpages
    - bearertokenauth
    - oidc
    - host_observer
    - sigv4auth
    - file_storage
    - memory_ballast
    - health_check
    - oauth2client
    - awsproxy
    - http_forwarder
    - jaegerremotesampling
    - k8s_observer
    - pprof
    - asapclient
    - basicauth
    - headers_setter

この拡張機能は、エクスポーターが設定されたエンドポイントにデータを送信できない場合に、エクスポーターがデータをディスクにキューイングする機能を提供します。

拡張機能を設定するには、以下の情報を含めるように設定を更新する必要があります。まず、/tmp/otel-data ディレクトリを作成し、読み書き権限を付与してください

extensions:
...
  file_storage:
    directory: /tmp/otel-data
    timeout: 10s
    compaction:
      directory: /tmp/otel-data
      on_start: true
      on_rebound: true
      rebound_needed_threshold_mib: 5
      rebound_trigger_threshold_mib: 3

# ... truncated for clarity

service:
  extensions: [health_check, pprof, zpages, file_storage]

なぜデータをディスクにキューイングするのか？

これにより、Collector はネットワークの中断（さらには Collector の再起動）を乗り越えて、データがアップストリームプロバイダーに送信されることを保証できます。

データをディスクにキューイングする際の考慮事項

ディスクのパフォーマンスにより、データスループットのパフォーマンスに影響を与える可能性があります。

参考資料

設定の確認

拡張機能について学んだので、設定の変更を確認しましょう。

Check-in設定を確認する

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
# See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md#safeguards-against-denial-of-service-attacks

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  opencensus:
    endpoint: 0.0.0.0:55678

  # Collect own metrics
  prometheus:
    config:
      scrape_configs:
      - job_name: 'otel-collector'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
      thrift_binary:
        endpoint: 0.0.0.0:6832
      thrift_compact:
        endpoint: 0.0.0.0:6831
      thrift_http:
        endpoint: 0.0.0.0:14268

  zipkin:
    endpoint: 0.0.0.0:9411

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [otlp, opencensus, prometheus]
      processors: [batch]
      exporters: [debug]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

  extensions: [health_check, pprof, zpages]

拡張機能について確認したので、次はワークショップのデータパイプライン部分に進みましょう。パイプラインは、Collector 内でデータが辿る経路を定義し、受信から始まり、さらなる処理や変更を経て、最終的にエクスポーターを通じて Collector を出ていきます。

OpenTelemetry Collector のデータパイプラインは、レシーバー、プロセッサー、エクスポーターで構成されています。まずはレシーバーから始めます。

OpenTelemetry Collector Receivers

ワークショップの Receiver セクションへようこそ！ここは OpenTelemetry Collector のデータパイプラインの出発点です。早速始めましょう。

Receiver は、プッシュベースまたはプルベースであり、データを Collector に取り込む方法です。Receiver は1つ以上のデータソースをサポートできます。一般的に、Receiver は指定された形式でデータを受け取り、内部形式に変換してから、該当するパイプラインで定義された Processor と Exporter に渡します。

%%{
  init:{
    "theme":"base",
    "themeVariables": {
      "primaryColor": "#ffffff",
      "clusterBkg": "#eff2fb",
      "defaultLinkColor": "#333333"
    }
  }
}%%

flowchart LR;
    style M fill:#e20082,stroke:#333,stroke-width:4px,color:#fff
    subgraph Collector
    A[OTLP] --> M(Receivers)
    B[JAEGER] --> M(Receivers)
    C[Prometheus] --> M(Receivers)
    end
    subgraph Processors
    M(Receivers) --> H(Filters, Attributes, etc)
    E(Extensions)
    end
    subgraph Exporters
    H(Filters, Attributes, etc) --> S(OTLP)
    H(Filters, Attributes, etc) --> T(JAEGER)
    H(Filters, Attributes, etc) --> U(Prometheus)
    end

OpenTelemetry Collector Receivers

Host Metrics Receiver

Host Metrics Receiver は、さまざまなソースからスクレイピングしたホストシステムに関するメトリクスを生成します。これは、Collector がエージェントとしてデプロイされる場合に使用することを想定しており、このワークショップでもその方法を採用します。

/etc/otel-contrib/config.yaml ファイルを更新して、hostmetrics Receiver を設定しましょう。以下の YAML を receivers セクションの下に挿入してください。インデントはスペース2つで行います。

sudo vi /etc/otelcol-contrib/config.yaml

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      # CPU utilization metrics
      cpu:
      # Disk I/O metrics
      disk:
      # File System utilization metrics
      filesystem:
      # Memory utilization metrics
      memory:
      # Network interface I/O metrics & TCP connection metrics
      network:
      # CPU load metrics
      load:
      # Paging/Swap space utilization and I/O metrics
      paging:
      # Process count metrics
      processes:
      # Per process CPU, Memory and Disk I/O metrics. Disabled by default.
      # process:

OpenTelemetry Collector Receivers

Prometheus Receiver

prometheus という別の Receiver があることにも気づくでしょう。Prometheus は、OpenTelemetry Collector が使用するオープンソースのツールキットです。この Receiver は、OpenTelemetry Collector 自体からメトリクスをスクレイピングするために使用されます。これらのメトリクスは、Collector の健全性を監視するために使用できます。

prometheus Receiver を変更して、Collector 自体からメトリクスを収集するためのものであることを明確にしましょう。Receiver の名前を prometheus から prometheus/internal に変更することで、その Receiver が何をしているかがより明確になります。設定ファイルを以下のように更新してください

prometheus/internal:
  config:
    scrape_configs:
    - job_name: 'otel-collector'
      scrape_interval: 10s
      static_configs:
      - targets: ['0.0.0.0:8888']

ダッシュボード例 - Prometheus メトリクス

以下のスクリーンショットは、Prometheus internal Receiver が OpenTelemetry Collector から収集するメトリクスの一部を表示するダッシュボード例です。ここでは、受け入れられたスパン、メトリクス、ログレコードと送信されたものを確認できます。

メモ

以下のスクリーンショットは、Splunk Observability Cloud の標準（OOTB）ダッシュボードで、Splunk OpenTelemetry Collector のインストール状況を簡単に監視できます。

OpenTelemetry Collector Receivers

その他の Receiver

デフォルト設定には、otlp、opencensus、jaeger、zipkin などの他の Receiver があることに気づくでしょう。これらは他のソースからテレメトリデータを受信するために使用されます。このワークショップではこれらの Receiver については取り上げませんので、そのままにしておいてください。

Ninja: Receiver を動的に作成する

Docker コンテナ、Kubernetes Pod、SSH セッションなどの短期間のタスクを監視するために、receiver creator と observer extensions を使用して、これらのサービスが起動するときに新しい Receiver を作成できます。

何が必要ですか？

receiver creator とそれに関連する observer extension を使い始めるには、それらが Collector のビルドマニフェストに含まれている必要があります。

詳細は installation を参照してください。

考慮すべき事項

一部の短期間のタスクでは、username や password などの追加設定が必要な場合があります。これらの値は環境変数で参照するか、 ${file:./path/to/database/password} のようなスキーム展開構文を使用できます。この方法を採用する場合は、組織のシークレット管理のベストプラクティスに従ってください。

Ninja ゾーン

この Ninja ゾーンに必要なことは2つだけです

ビルダーマニフェストに receiver creator と observer extension が追加されていることを確認します。
検出されたエンドポイントとマッチングするために使用できる設定を作成します。

テンプレート化された設定を作成するには、以下のようにします

receiver_creator:
  watch_observers: [host_observer]
  receivers:
    redis:
      rule: type == "port" && port == 6379
      config:
        password: ${env:HOST_REDIS_PASSWORD}

その他の例については、receiver creator の例を参照してください。

設定の確認

Receiver について説明しましたので、設定の変更を確認しましょう。

Check-in設定を確認する

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
# To limit exposure to denial of service attacks, change the host in endpoints below from 0.0.0.0 to a specific network interface.
# See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md#safeguards-against-denial-of-service-attacks

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      # CPU utilization metrics
      cpu:
      # Disk I/O metrics
      disk:
      # File System utilization metrics
      filesystem:
      # Memory utilization metrics
      memory:
      # Network interface I/O metrics & TCP connection metrics
      network:
      # CPU load metrics
      load:
      # Paging/Swap space utilization and I/O metrics
      paging:
      # Process count metrics
      processes:
      # Per process CPU, Memory and Disk I/O metrics. Disabled by default.
      # process:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  opencensus:
    endpoint: 0.0.0.0:55678

  # Collect own metrics
  prometheus/internal:
    config:
      scrape_configs:
      - job_name: 'otel-collector'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
      thrift_binary:
        endpoint: 0.0.0.0:6832
      thrift_compact:
        endpoint: 0.0.0.0:6831
      thrift_http:
        endpoint: 0.0.0.0:14268

  zipkin:
    endpoint: 0.0.0.0:9411

processors:
  batch:

exporters:
  debug:
    verbosity: detailed

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [otlp, opencensus, prometheus]
      processors: [batch]
      exporters: [debug]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

  extensions: [health_check, pprof, zpages]

Receiver を通じてデータが OpenTelemetry Collector にどのように取り込まれるかを確認しました。次は、Collector が受信したデータをどのように処理するかを見ていきましょう。

警告

/etc/otelcol-contrib/config.yaml はまだ完成していないため、この時点では Collector を再起動しないでください。

OpenTelemetry Collector Processors

Processors は、データを受信してからエクスポートするまでの間に実行されます。Processors はオプションですが、一部は推奨されています。OpenTelemetry contrib Collector には 多数の Processors が含まれています。

%%{
  init:{
    "theme":"base",
    "themeVariables": {
      "primaryColor": "#ffffff",
      "clusterBkg": "#eff2fb",
      "defaultLinkColor": "#333333"
    }
  }
}%%

flowchart LR;
    style Processors fill:#e20082,stroke:#333,stroke-width:4px,color:#fff
    subgraph Collector
    A[OTLP] --> M(Receivers)
    B[JAEGER] --> M(Receivers)
    C[Prometheus] --> M(Receivers)
    end
    subgraph Processors
    M(Receivers) --> H(Filters, Attributes, etc)
    E(Extensions)
    end
    subgraph Exporters
    H(Filters, Attributes, etc) --> S(OTLP)
    H(Filters, Attributes, etc) --> T(JAEGER)
    H(Filters, Attributes, etc) --> U(Prometheus)
    end

OpenTelemetry Collector Processors

Batch Processor

デフォルトでは、batch processor のみが有効になっています。この processor は、データをエクスポートする前にバッチ処理するために使用されます。これは、exporter へのネットワーク呼び出しの回数を減らすのに役立ちます。このワークショップでは、Collector にハードコードされている以下のデフォルト値を継承します

send_batch_size（デフォルト = 8192）：タイムアウトに関係なくバッチが送信されるスパン、メトリクスデータポイント、またはログレコードの数。send_batch_size はトリガーとして機能し、バッチのサイズには影響しません。パイプラインの次のコンポーネントに送信されるバッチサイズの制限を強制する必要がある場合は、send_batch_max_size を参照してください。
timeout（デフォルト = 200ms）：サイズに関係なくバッチが送信されるまでの時間。ゼロに設定すると、send_batch_max_size のみに従ってデータが即座に送信されるため、send_batch_size は無視されます。
send_batch_max_size（デフォルト = 0）：バッチサイズの上限。0 はバッチサイズに上限がないことを意味します。このプロパティは、大きなバッチを小さな単位に分割することを保証します。send_batch_size 以上である必要があります。

Batch processor の詳細については、Batch Processor のドキュメントを参照してください。

OpenTelemetry Collector Processors

Resource Detection Processor

resourcedetection processor は、ホストからリソース情報を検出し、テレメトリデータのリソース値にこの情報を追加または上書きするために使用できます。

デフォルトでは、ホスト名は可能であれば FQDN に設定され、それ以外の場合は OS が提供するホスト名がフォールバックとして使用されます。このロジックは hostname_sources 設定オプションを使用して変更できます。FQDN を取得せずに OS が提供するホスト名を使用するには、hostname_sources を os に設定します。

processors:
  batch:
  resourcedetection/system:
    detectors: [system]
    system:
      hostname_sources: [os]

ワークショップインスタンスが AWS/EC2 インスタンスで実行されている場合、EC2 メタデータ API から以下のタグを収集できます（これは他のプラットフォームでは利用できません）。

cloud.provider ("aws")
cloud.platform ("aws_ec2")
cloud.account.id
cloud.region
cloud.availability_zone
host.id
host.image.id
host.name
host.type

これらのタグをメトリクスに追加するために、別の processor を作成します。

processors:
  batch:
  resourcedetection/system:
    detectors: [system]
    system:
      hostname_sources: [os]
  resourcedetection/ec2:
    detectors: [ec2]

OpenTelemetry Collector Processors

Attributes Processor

attributes processor は、スパン、ログ、またはメトリクスの属性を変更します。この processor は、指定されたアクションに含めるか除外するかを決定するために、入力データをフィルタリングおよびマッチングする機能もサポートしています。

設定で指定された順序で実行されるアクションのリストを受け取ります。サポートされているアクションは以下の通りです

insert：キーがまだ存在しない入力データに新しい属性を挿入します。
update：キーが存在する入力データの属性を更新します。
upsert：insert または update を実行します。キーがまだ存在しない入力データに新しい属性を挿入し、キーが存在する入力データの属性を更新します。
delete：入力データから属性を削除します。
hash：既存の属性値をハッシュ化（SHA1）します。
extract：正規表現ルールを使用して入力キーからルールで指定されたターゲットキーに値を抽出します。ターゲットキーがすでに存在する場合は上書きされます。

すべてのホストメトリクスに participant.name という新しい属性を insert する attributes processor を作成します。値にはあなたの名前（例：marge_simpson）を設定します。

警告

INSERT_YOUR_NAME_HERE を必ずあなたの名前に置き換えてください。また、名前にスペースを使用しないようにしてください。

ワークショップの後半で、Splunk Observability Cloud でメトリクスをフィルタリングするためにこの属性を使用します。

processors:
  batch:
  resourcedetection/system:
    detectors: [system]
    system:
      hostname_sources: [os]
  resourcedetection/ec2:
    detectors: [ec2]
  attributes/conf:
    actions:
      - key: participant.name
        action: insert
        value: "INSERT_YOUR_NAME_HERE"

Ninja: connector を使用して内部インサイトを取得する

Collector への最新の追加機能の1つは connector の概念で、あるパイプラインの出力を別のパイプラインの入力に接続できます。

これが有益な例として、一部のサービスはエクスポートされるデータポイントの量、エラーステータスを含むログの数、または特定のデプロイ環境から送信されるデータ量に基づいてメトリクスを出力します。count connector はこれをすぐに使える形で対処するのに役立ちます。

processor の代わりに connector を使用する理由

processor は処理したデータを渡す必要があるため、追加データを生成する点で制限があり、追加情報を公開するのが困難です。connector は受信したデータを出力する必要がないため、求めているインサイトを作成する機会を提供します。

例えば、デプロイ環境属性を持たないログ、メトリクス、トレースの数をカウントする connector を作成できます。

デプロイ環境別にデータ使用量を分類できる非常にシンプルな例です。

connector に関する考慮事項

connector は、あるパイプラインからエクスポートされ、別のパイプラインで受信されたデータのみを受け入れます。これは、connector を活用するために Collector の設定をどのように構成するかを検討する必要があることを意味します。

参考資料

設定の確認

processors について説明しました。設定の変更を確認しましょう。

Check-in設定を確認する

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
# To limit exposure to denial of service attacks, change the host in endpoints below from 0.0.0.0 to a specific network interface.
# See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md#safeguards-against-denial-of-service-attacks

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      # CPU utilization metrics
      cpu:
      # Disk I/O metrics
      disk:
      # File System utilization metrics
      filesystem:
      # Memory utilization metrics
      memory:
      # Network interface I/O metrics & TCP connection metrics
      network:
      # CPU load metrics
      load:
      # Paging/Swap space utilization and I/O metrics
      paging:
      # Process count metrics
      processes:
      # Per process CPU, Memory and Disk I/O metrics. Disabled by default.
      # process:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  opencensus:
    endpoint: 0.0.0.0:55678

  # Collect own metrics
  prometheus/internal:
    config:
      scrape_configs:
      - job_name: 'otel-collector'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
      thrift_binary:
        endpoint: 0.0.0.0:6832
      thrift_compact:
        endpoint: 0.0.0.0:6831
      thrift_http:
        endpoint: 0.0.0.0:14268

  zipkin:
    endpoint: 0.0.0.0:9411

processors:
  batch:
  resourcedetection/system:
    detectors: [system]
    system:
      hostname_sources: [os]
  resourcedetection/ec2:
    detectors: [ec2]
  attributes/conf:
    actions:
      - key: participant.name
        action: insert
        value: "INSERT_YOUR_NAME_HERE"

exporters:
  debug:
    verbosity: detailed

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [otlp, opencensus, prometheus]
      processors: [batch]
      exporters: [debug]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

  extensions: [health_check, pprof, zpages]

OpenTelemetry Collector Exporters

Exporter はプッシュ型またはプル型で、1つ以上のバックエンド/宛先にデータを送信する方法です。Exporter は1つ以上のデータソースをサポートする場合があります。

このワークショップでは、otlphttp exporter を使用します。OpenTelemetry Protocol (OTLP) は、テレメトリデータを送信するためのベンダー中立で標準化されたプロトコルです。OTLP exporter は、OTLP プロトコルを実装しているサーバーにデータを送信します。OTLP exporter は gRPC と HTTP/JSON の両方のプロトコルをサポートしています。

%%{
  init:{
    "theme":"base",
    "themeVariables": {
      "primaryColor": "#ffffff",
      "clusterBkg": "#eff2fb",
      "defaultLinkColor": "#333333"
    }
  }
}%%

flowchart LR;
    style Exporters fill:#e20082,stroke:#333,stroke-width:4px,color:#fff
    subgraph Collector
    A[OTLP] --> M(Receivers)
    B[JAEGER] --> M(Receivers)
    C[Prometheus] --> M(Receivers)
    end
    subgraph Processors
    M(Receivers) --> H(Filters, Attributes, etc)
    E(Extensions)
    end
    subgraph Exporters
    H(Filters, Attributes, etc) --> S(OTLP)
    H(Filters, Attributes, etc) --> T(JAEGER)
    H(Filters, Attributes, etc) --> U(Prometheus)
    end

OpenTelemetry Collector Exporters

OTLP HTTP Exporter

HTTP 経由で Splunk Observability Cloud にメトリクスを送信するには、otlphttp exporter を設定する必要があります。

/etc/otelcol-contrib/config.yaml ファイルを編集して、otlphttp exporter を設定しましょう。以下の YAML を exporters セクションの下に挿入してください。インデントは2スペースで行ってください。

また、ディスクがいっぱいにならないように、logging exporter の詳細度を変更します。デフォルトの detailed は非常に冗長です。

exporters:
  logging:
    verbosity: normal
  otlphttp/splunk:

次に、metrics_endpoint を定義してターゲット URL を設定する必要があります。

メモ

Splunk 主催のワークショップに参加されている場合、使用しているインスタンスにはすでに Realm 環境変数が設定されています。設定ファイルでその環境変数を参照します。それ以外の場合は、新しい環境変数を作成して Realm を設定する必要があります。例

export REALM="us1"

使用する URL は https://ingest.${env:REALM}.signalfx.com/v2/datapoint/otlp です。（Splunk は、データレジデンシーのために世界中の主要な地理的場所に Realm を持っています）。

otlphttp exporter は、traces_endpoint と logs_endpoint のターゲット URL を定義することで、トレースとログを送信するように設定することもできます。これらの設定は、このワークショップの範囲外です。

exporters:
  logging:
    verbosity: normal
  otlphttp/splunk:
    metrics_endpoint: https://ingest.${env:REALM}.signalfx.com/v2/datapoint/otlp

デフォルトでは、すべてのエンドポイントで gzip 圧縮が有効になっています。これは、exporter 設定で compression: none を設定することで無効にできます。このワークショップでは、データを送信する最も効率的な方法であるため、圧縮を有効のままにしてデフォルトを使用します。

Splunk Observability Cloud にメトリクスを送信するには、アクセストークンを使用する必要があります。これは、Splunk Observability Cloud UI で新しいトークンを作成することで行えます。トークンの作成方法の詳細については、Create a token を参照してください。トークンは INGEST タイプである必要があります。

メモ

Splunk 主催のワークショップに参加されている場合、使用しているインスタンスにはすでにアクセストークンが設定されています（環境変数として設定されています）。設定ファイルでその環境変数を参照します。それ以外の場合は、新しいトークンを作成して環境変数として設定する必要があります。例

export ACCESS_TOKEN=<replace-with-your-token>

トークンは、headers: セクションの下に X-SF-TOKEN: ${env:ACCESS_TOKEN} を挿入することで設定ファイルに定義されます

exporters:
  logging:
    verbosity: normal
  otlphttp/splunk:
    metrics_endpoint: https://ingest.${env:REALM}.signalfx.com/v2/datapoint/otlp
    headers:
      X-SF-TOKEN: ${env:ACCESS_TOKEN}

設定の確認

Exporter について説明したので、設定の変更を確認しましょう

Check-inReview your configuration

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
# To limit exposure to denial of service attacks, change the host in endpoints below from 0.0.0.0 to a specific network interface.
# See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md#safeguards-against-denial-of-service-attacks

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      # CPU utilization metrics
      cpu:
      # Disk I/O metrics
      disk:
      # File System utilization metrics
      filesystem:
      # Memory utilization metrics
      memory:
      # Network interface I/O metrics & TCP connection metrics
      network:
      # CPU load metrics
      load:
      # Paging/Swap space utilization and I/O metrics
      paging:
      # Process count metrics
      processes:
      # Per process CPU, Memory and Disk I/O metrics. Disabled by default.
      # process:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  opencensus:
    endpoint: 0.0.0.0:55678

  # Collect own metrics
  prometheus/internal:
    config:
      scrape_configs:
      - job_name: 'otel-collector'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
      thrift_binary:
        endpoint: 0.0.0.0:6832
      thrift_compact:
        endpoint: 0.0.0.0:6831
      thrift_http:
        endpoint: 0.0.0.0:14268

  zipkin:
    endpoint: 0.0.0.0:9411

processors:
  batch:
  resourcedetection/system:
    detectors: [system]
    system:
      hostname_sources: [os]
  resourcedetection/ec2:
    detectors: [ec2]
  attributes/conf:
    actions:
      - key: participant.name
        action: insert
        value: "INSERT_YOUR_NAME_HERE"

exporters:
  debug:
    verbosity: normal
  otlphttp/splunk:
    metrics_endpoint: https://ingest.${env:REALM}.signalfx.com/v2/datapoint/otlp
    headers:
      X-SF-Token: ${env:ACCESS_TOKEN}

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [otlp, opencensus, prometheus]
      processors: [batch]
      exporters: [debug]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

  extensions: [health_check, pprof, zpages]

もちろん、OTLP プロトコルをサポートする他のソリューションを指すように metrics_endpoint を簡単に設定できます。

次に、config.yaml の service セクションで、設定した receivers、processors、exporters を有効にする必要があります。

OpenTelemetry Collector Service

Service セクションは、receivers、processors、exporters、extensions セクションで定義された設定に基づいて、Collector でどのコンポーネントを有効にするかを設定するために使用します。

情報

コンポーネントが設定されていても、Service セクション内で定義されていない場合、そのコンポーネントは有効になりません。

service セクションは3つのサブセクションで構成されています

extensions
pipelines
telemetry

デフォルト設定では、extension セクションは health_check、pprof、zpages を有効にするよう設定されています。これらは先ほど Extensions モジュールで設定しました。

service:
  extensions: [health_check, pprof, zpages]

それでは、Metric Pipeline を設定しましょう！

OpenTelemetry Collector Service

Hostmetrics Receiver

ワークショップの Receivers セクションで、さまざまなソースからスクレイプされるホストシステムに関するメトリクスを生成する Host Metrics Receiver を定義したことを思い出してください。この receiver を有効にするには、metrics パイプラインに hostmetrics receiver を含める必要があります。

metrics パイプラインで、metrics の receivers セクションに hostmetrics を追加します。

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [hostmetrics, otlp, opencensus, prometheus]
      processors: [batch]
      exporters: [debug]

OpenTelemetry Collector Service

Prometheus Internal Receiver

ワークショップの前半で、Collector 内部のメトリクスを収集していることを反映するために prometheus receiver の名前を prometheus/internal に変更しました。

ここで、metrics パイプラインで prometheus/internal receiver を有効にする必要があります。metrics パイプラインの receivers セクションに prometheus/internal を含めるように更新します

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [hostmetrics, otlp, opencensus, prometheus/internal]
      processors: [batch]
      exporters: [debug]

OpenTelemetry Collector Service

Resource Detection Processor

また、Collector がインスタンスのホスト名と AWS/EC2 メタデータをキャプチャできるように、resourcedetection/system と resourcedetection/ec2 processor を追加しました。ここで、metrics パイプラインでこれら2つの processor を有効にする必要があります。

metrics パイプラインの processors セクションに resourcedetection/system と resourcedetection/ec2 を含めるように更新します

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [hostmetrics, otlp, opencensus, prometheus/internal]
      processors: [batch, resourcedetection/system, resourcedetection/ec2]
      exporters: [debug]

OpenTelemetry Collector Service

Attributes Processor

また、このワークショップの Processors セクションで、Collector がすべてのメトリクスに participant.name という新しい属性を挿入するように attributes/conf processor を追加しました。ここで、metrics パイプラインでこれを有効にする必要があります。

metrics パイプラインの processors セクションに attributes/conf を含めるように更新します

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [hostmetrics, otlp, opencensus, prometheus/internal]
      processors: [batch, resourcedetection/system, resourcedetection/ec2, attributes/conf]
      exporters: [debug]

OpenTelemetry Collector Service

OTLP HTTP Exporter

ワークショップの Exporters セクションで、メトリクスを Splunk Observability Cloud に送信するための otlphttp exporter を設定しました。ここで、metrics パイプラインでこれを有効にする必要があります。

metrics パイプラインの exporters セクションに otlphttp/splunk を含めるように更新します

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [hostmetrics, otlp, opencensus, prometheus/internal]
      processors: [batch, resourcedetection/system, resourcedetection/ec2, attributes/conf]
      exporters: [debug, otlphttp/splunk]

Ninja: Collector の内部を観察する

Collector は、実行中のコンポーネントからの追加シグナルを含む、自身の動作に関する内部シグナルをキャプチャします。これは、データフローに関する判断を行うコンポーネントが、その情報をメトリクスまたはトレースとして公開する方法を必要とするためです。

なぜ Collector を監視するのか？

これは「監視者を誰が監視するのか？」という、鶏と卵のような問題ですが、この情報を公開できることは重要です。Collector の歴史において興味深い点は、Go メトリクス SDK が安定版と見なされる前から存在していたため、当面の間、Collector はこの機能を提供するために Prometheus エンドポイントを公開しているということです。

考慮事項

組織内で実行中の各 Collector の内部使用状況を監視すると、大量の新しい Metric Time Series (MTS) が発生する可能性があります。Splunk ディストリビューションでは、これらのメトリクスが厳選されており、予想される増加を予測するのに役立ちます。

Ninja Zone

Collector の内部オブザーバビリティを公開するために、いくつかの追加設定を調整できます

service:
  telemetry:
    logs:
      level: <info|warn|error>
      development: <true|false>
      encoding: <console|json>
      disable_caller: <true|false>
      disable_stacktrace: <true|false>
      output_paths: [<stdout|stderr>, paths...]
      error_output_paths: [<stdout|stderr>, paths...]
      initial_fields:
        key: value
    metrics:
      level: <none|basic|normal|detailed>
      # Address binds the promethues endpoint to scrape
      address: <hostname:port>

service:
  telemetry:
    logs:
      level: info
      encoding: json
      disable_stacktrace: true
      initial_fields:
        instance.name: ${env:INSTANCE}
    metrics:
      address: localhost:8888

参考資料

https://opentelemetry.io/docs/collector/configuration/#service

最終設定

Check-in最終設定を確認する

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
# To limit exposure to denial of service attacks, change the host in endpoints below from 0.0.0.0 to a specific network interface.
# See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md#safeguards-against-denial-of-service-attacks

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      # CPU utilization metrics
      cpu:
      # Disk I/O metrics
      disk:
      # File System utilization metrics
      filesystem:
      # Memory utilization metrics
      memory:
      # Network interface I/O metrics & TCP connection metrics
      network:
      # CPU load metrics
      load:
      # Paging/Swap space utilization and I/O metrics
      paging:
      # Process count metrics
      processes:
      # Per process CPU, Memory and Disk I/O metrics. Disabled by default.
      # process:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

  opencensus:
    endpoint: 0.0.0.0:55678

  # Collect own metrics
  prometheus/internal:
    config:
      scrape_configs:
      - job_name: 'otel-collector'
        scrape_interval: 10s
        static_configs:
        - targets: ['0.0.0.0:8888']

  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
      thrift_binary:
        endpoint: 0.0.0.0:6832
      thrift_compact:
        endpoint: 0.0.0.0:6831
      thrift_http:
        endpoint: 0.0.0.0:14268

  zipkin:
    endpoint: 0.0.0.0:9411

processors:
  batch:
  resourcedetection/system:
    detectors: [system]
    system:
      hostname_sources: [os]
  resourcedetection/ec2:
    detectors: [ec2]
  attributes/conf:
    actions:
      - key: participant.name
        action: insert
        value: "INSERT_YOUR_NAME_HERE"

exporters:
  debug:
    verbosity: normal
  otlphttp/splunk:
    metrics_endpoint: https://ingest.${env:REALM}.signalfx.com/v2/datapoint/otlp
    headers:
      X-SF-Token: ${env:ACCESS_TOKEN}

service:

  pipelines:

    traces:
      receivers: [otlp, opencensus, jaeger, zipkin]
      processors: [batch]
      exporters: [debug]

    metrics:
      receivers: [hostmetrics, otlp, opencensus, prometheus/internal]
      processors: [batch, resourcedetection/system, resourcedetection/ec2, attributes/conf]
      exporters: [debug, otlphttp/splunk]

    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]

  extensions: [health_check, pprof, zpages]

ヒント

Collector を再起動する前に、設定ファイルを検証することをお勧めします。config.yaml ファイルの内容を otelbin.io に貼り付けることで検証できます。

ScreenshotOTelBin

これで動作する設定ができたので、Collector を起動して zPages が何を報告しているか確認しましょう。

otelcol-contrib --config=file:/etc/otelcol-contrib/config.yaml

ブラウザで zPages を開きます：http://localhost:55679/debug/pipelinez（localhost を自分の環境に合わせて変更してください）。

データの可視化

Splunk Observability Cloud

OpenTelemetry Collector からメトリクスを Splunk Observability Cloud に送信する設定が完了したので、Splunk Observability Cloud でデータを確認してみましょう。Splunk Observability Cloud への招待を受け取っていない場合は、インストラクターがログイン資格情報を提供します。

その前に、少し面白くするためにインスタンスでストレステストを実行してみましょう。これによりダッシュボードが活性化されます。

sudo apt install stress
while true; do stress -c 2 -t 40; stress -d 5 -t 40; stress -m 20 -t 40; done

Splunk Observability Cloud にログインしたら、左側のナビゲーションを使用してメインメニューから Dashboards に移動します。これによりチームビューが表示されます。このビューの上部にある All Dashboards をクリックします

検索ボックスで OTel Contrib を検索します

情報

ダッシュボードが存在しない場合は、インストラクターがすぐに追加できます。Splunk 主催のワークショップに参加していない場合は、インポートするダッシュボードグループをこのページの下部で見つけることができます。

OTel Contrib Dashboard ダッシュボードをクリックして開き、次にダッシュボード上部の Participant Name ボックスをクリックして、config.yaml で participant.name に設定した名前をドロップダウンリストから選択するか、名前を入力して検索します

これで、OpenTelemetry Collector を設定したホストのホストメトリクスを確認できます。

Download Dashboard Group JSON for importing

OpenTelemetry-Contrib-Dashboard-Group.json (40 KB)

OpenTelemetry Collector 開発

カスタムコンポーネントの開発

OpenTelemetry Collector 用のコンポーネントを構築するには、3つの主要な部分が必要です

Configuration - ユーザーに公開される設定値
Factory - 提供された値を使用してコンポーネントを作成する
Business Logic - コンポーネントが実行する必要がある処理

ここでは、プロジェクトの重要な DevOps メトリクスを追跡できるように、Jenkins と連携するコンポーネントを構築する例を使用します。

測定しようとしているメトリクスは以下の通りです

Lead time for changes - “コミットが本番環境にデプロイされるまでにかかる時間”
Change failure rate - “本番環境で障害を引き起こすデプロイメントの割合”
Deployment frequency - "[チーム]が本番環境に正常にリリースする頻度"
Mean time to recover - "[チーム]が本番環境の障害から復旧するまでにかかる時間"

これらの指標は、ソフトウェア開発チームのパフォーマンスを示すために、Google の DevOps Research and Assessment（DORA）[^1] チームによって特定されました。Jenkins CI を選択した理由は、同じオープンソースソフトウェアのエコシステム内にとどまることで、将来ベンダーが管理する CI ツールが採用するための例として機能できるからです。

計装 vs コンポーネント

組織内のオブザーバビリティのレベルを向上させる際に考慮すべきことがあります。いくつかのトレードオフが生じるためです。

	メリット	デメリット
（自動）計装	システムを監視するために外部 API を監視する必要がありません。	計装を変更するにはプロジェクトへの変更が必要です。
	システムオーナー/開発者がオブザーバビリティを変更する権限を持てます。	追加のランタイム依存関係が必要です。
	システムコンテキストを理解し、キャプチャしたデータを Exemplars と関連付けることができます。	システムのパフォーマンスに影響を与える可能性があります。
コンポーネント	データ名やセマンティクスへの変更をシステムのリリースサイクルとは独立して展開できます。	API の破壊的な変更には、システムと Collector の間で調整されたリリースが必要です。
	収集されるデータの更新/拡張は、ユーザーにとってシームレスな変更です。	キャプチャされたデータのセマンティクスが、新しいシステムリリースと一致しない形で予期せず壊れる可能性があります。
	サポートチームがオブザーバビリティの実践について深い理解を持つ必要がありません。	システムから外部に公開された情報のみを表面化できます。

OpenTelemetry Collector 開発

プロジェクトのセットアップ Ninja

メモ

このワークショップセクションを完了するまでの時間は、経験によって異なります。

行き詰まった場合やインストラクターに沿って進めたい場合は、こちらに完全なソリューションがあります。

新しい Jenkins CI レシーバーの開発を始めるには、まず Golang プロジェクトをセットアップする必要があります。新しい Golang プロジェクトを作成する手順は以下の通りです

${HOME}/go/src/jenkinscireceiver という名前の新しいディレクトリを作成し、そのディレクトリに移動します
1. 実際のディレクトリ名や場所は厳密ではなく、独自の開発ディレクトリを選択して作成できます。
go mod init splunk.conf/workshop/example/jenkinscireceiver を実行して golang モジュールを初期化します
1. これにより go.mod というファイルが作成され、直接的および間接的な依存関係を追跡するために使用されます
2. 最終的には、インポートされる依存関係のチェックサム値である go.sum が生成されます。

Check-ingo.mod を確認する

module splunk.conf/workshop/example/jenkinscireceiver

go 1.20

OpenTelemetry Collector 開発

Configuration の構築

コンポーネントの Configuration 部分は、ユーザーがコンポーネントに対して入力を行う方法です。そのため、設定に使用される値は以下の条件を満たす必要があります

そのフィールドが何を制御するかをユーザーが直感的に理解できること
必須と任意を明確にすること
一般的な名前とフィールドを再利用すること
オプションをシンプルに保つこと

---
jenkins_server_addr: hostname
jenkins_server_api_port: 8089
interval: 10m
filter_builds_by:
    - name: my-awesome-build
      status: amber
track:
    values:
        example.metric.1: yes
        example.metric.2: yes
        example.metric.3: no
        example.metric.4: no

---
# Required Values
endpoint: http://my-jenkins-server:8089
auth:
    authenticator: basicauth/jenkins
# Optional Values
collection_interval: 10m
metrics:
    example.metric.1:
        enabled: true
    example.metric.2:
        enabled: true
    example.metric.3:
        enabled: true
    example.metric.4:
        enabled: true

悪い設定例は、設定のベストプラクティスの逆を行うことがコンポーネントの使いやすさにどのように影響するかを示しています。フィールド値が何であるべきかが明確ではなく、既存のプロセッサにプッシュできる機能が含まれており、フィールド名が Collector に存在する他のコンポーネントと一貫していません。

良い設定例は、必須の値をシンプルに保ち、他のコンポーネントからフィールド名を再利用し、コンポーネントが Jenkins と Collector 間の相互作用のみに焦点を当てることを確保しています。

コードタブは、私たちが追加する必要がある量と、Collector 内の共有ライブラリによってすでに提供されているものを示しています。これらはビジネスロジックに到達したときにより詳細に説明します。Configuration は小さく始まり、追加機能が必要になるとビジネスロジックが含まれるようになると変更されます。

コードを書く

Configuration に必要なコードを実装するために、以下の内容で config.go という新しいファイルを作成します

package jenkinscireceiver

import (
    "go.opentelemetry.io/collector/config/confighttp"
    "go.opentelemetry.io/collector/receiver/scraperhelper"

    "splunk.conf/workshop/example/jenkinscireceiver/internal/metadata"
)

type Config struct {
    // HTTPClientSettings contains all the values
    // that are commonly shared across all HTTP interactions
    // performed by the collector.
    confighttp.HTTPClientSettings `mapstructure:",squash"`
    // ScraperControllerSettings will allow us to schedule
    // how often to check for updates to builds.
    scraperhelper.ScraperControllerSettings `mapstructure:",squash"`
    // MetricsBuilderConfig contains all the metrics
    // that can be configured.
    metadata.MetricsBuilderConfig `mapstructure:",squash"`
}

OpenTelemetry Collector 開発

コンポーネントのレビュー

Jenkins からメトリクスをキャプチャするために必要なコンポーネントの種類を振り返ります

Extension が解決するビジネスユースケースは以下の通りです

ランタイム設定が必要な共有機能を持つこと
Collector のランタイムを観測することを間接的に支援すること

詳細は Extensions の概要 を参照してください。

Receiver が解決するビジネスユースケースは以下の通りです

リモートソースからデータをフェッチする
リモートソースからデータを受信する

これは一般的に pull 型と push 型のデータ収集と呼ばれ、詳細は Receiver の概要で読むことができます。

Processor が解決するビジネスユースケースは以下の通りです

データ、フィールド、または値の追加や削除
データを観測し、意思決定を行う
バッファリング、キューイング、並び替え

留意すべき点は、Processor を流れるデータタイプは、下流のコンポーネントに同じデータタイプを転送する必要があるということです。詳細は Processor の概要をお読みください。

Exporter が解決するビジネスユースケースは以下の通りです

ツール、サービス、またはストレージにデータを送信する

OpenTelemetry Collector は「バックエンド」、つまりオールインワンのオブザーバビリティスイートになることを望んでおらず、むしろ OpenTelemetry を創設した原則を維持しています。つまり、すべての人のためのベンダーに依存しないオブザーバビリティです。詳細を再確認するには、Exporter の概要 をお読みください。

これはワークショップで見逃されたコンポーネントタイプです。比較的新しい Collector への追加であるためです。Connector を考える最良の方法は、異なるテレメトリタイプとパイプライン間で使用できる Processor のようなものです。つまり、Connector はログとしてデータを受け入れ、メトリクスを出力したり、あるパイプラインからメトリクスを受け入れ、観測したデータに関するメトリクスを提供したりできます。

Connector が解決するビジネスケースは以下の通りです

異なるテレメトリタイプ間の変換
- ログからメトリクス
- トレースからメトリクス
- メトリクスからログ
受信データを観測し、独自のデータを生成する
- メトリクスを受け入れ、データの分析メトリクスを生成する。

Processor の概要の Ninja セクションに簡単な概要がありました。新しい Connector コンポーネントの更新についてはプロジェクトを確認してください。

コンポーネントの概要から、Jenkins 用のプルベースのレシーバーを開発することが明確です。

OpenTelemetry Collector 開発

メトリクスの設計

レシーバーでキャプチャしたメトリクスを定義およびエクスポートするために、mdatagen を使用します。これは、YAML で定義されたメトリクスをコードに変換する Collector 用に開発されたツールです。

---
# Type defines the name to reference the component
# in the configuration file
type: jenkins

# Status defines the component type and the stability level
status:
  class: receiver
  stability:
    development: [metrics]

# Attributes are the expected fields reported
# with the exported values.
attributes:
  job.name:
    description: The name of the associated Jenkins job
    type: string
  job.status:
    description: Shows if the job had passed, or failed
    type: string
    enum:
    - failed
    - success
    - unknown

# Metrics defines all the pontentially exported values from this receiver.
metrics:
  jenkins.jobs.count:
    enabled: true
    description: Provides a count of the total number of configured jobs
    unit: "{Count}"
    gauge:
      value_type: int
  jenkins.job.duration:
    enabled: true
    description: Show the duration of the job
    unit: "s"
    gauge:
      value_type: int
    attributes:
    - job.name
    - job.status
  jenkins.job.commit_delta:
    enabled: true
    description: The calculation difference of the time job was finished minus commit timestamp
    unit: "s"
    gauge:
      value_type: int
    attributes:
    - job.name
    - job.status

// To generate the additional code needed to capture metrics,
// the following command to be run from the shell:
//  go generate -x ./...

//go:generate go run github.com/open-telemetry/opentelemetry-collector-contrib/cmd/mdatagen@v0.80.0 metadata.yaml
package jenkinscireceiver

// There is no code defined within this file.

次のセクションに進む前に、これらのファイルをプロジェクトフォルダー内に作成してください。

Factory の構築

Factory は、オブジェクト（この場合は jenkinscireceiver）を提供された設定で動的に作成できるようにするソフトウェアデザインパターンです。より現実世界の例を使うと、電話ショップに行き、自分の説明と正確に一致する電話を求め、それを提供してもらうようなものです。

go generate -x ./... コマンドを実行すると、定義されたメトリクスをエクスポートするために必要なすべてのコードを含む新しいフォルダー jenkinscireceiver/internal/metadata が作成されます。必要なコードは以下の通りです

package jenkinscireceiver

import (
    "errors"

    "go.opentelemetry.io/collector/component"
    "go.opentelemetry.io/collector/config/confighttp"
    "go.opentelemetry.io/collector/receiver"
    "go.opentelemetry.io/collector/receiver/scraperhelper"

    "splunk.conf/workshop/example/jenkinscireceiver/internal/metadata"
)

func NewFactory() receiver.Factory {
    return receiver.NewFactory(
        metadata.Type,
        newDefaultConfig,
        receiver.WithMetrics(newMetricsReceiver, metadata.MetricsStability),
    )
}

func newMetricsReceiver(_ context.Context, set receiver.CreateSettings, cfg component.Config, consumer consumer.Metrics) (receiver.Metrics, error) {
    // Convert the configuration into the expected type
    conf, ok := cfg.(*Config)
    if !ok {
        return nil, errors.New("can not convert config")
    }
    sc, err := newScraper(conf, set)
    if err != nil {
        return nil, err
    }
    return scraperhelper.NewScraperControllerReceiver(
        &conf.ScraperControllerSettings,
        set,
        consumer,
        scraperhelper.AddScraper(sc),
    )
}

package jenkinscireceiver

import (
    "go.opentelemetry.io/collector/config/confighttp"
    "go.opentelemetry.io/collector/receiver/scraperhelper"

    "splunk.conf/workshop/example/jenkinscireceiver/internal/metadata"
)

type Config struct {
    // HTTPClientSettings contains all the values
    // that are commonly shared across all HTTP interactions
    // performed by the collector.
    confighttp.HTTPClientSettings `mapstructure:",squash"`
    // ScraperControllerSettings will allow us to schedule
    // how often to check for updates to builds.
    scraperhelper.ScraperControllerSettings `mapstructure:",squash"`
    // MetricsBuilderConfig contains all the metrics
    // that can be configured.
    metadata.MetricsBuilderConfig `mapstructure:",squash"`
}

func newDefaultConfig() component.Config {
    return &Config{
        ScraperControllerSettings: scraperhelper.NewDefaultScraperControllerSettings(metadata.Type),
        HTTPClientSettings:        confighttp.NewDefaultHTTPClientSettings(),
        MetricsBuilderConfig:      metadata.DefaultMetricsBuilderConfig(),
    }
}

package jenkinscireceiver

type scraper struct {}

func newScraper(cfg *Config, set receiver.CreateSettings) (scraperhelper.Scraper, error) {
    // Create a our scraper with our values
    s := scraper{
        // To be filled in later
    }
    return scraperhelper.NewScraper(metadata.Type, s.scrape)
}

func (scraper) scrape(ctx context.Context) (pmetric.Metrics, error) {
    // To be filled in
    return pmetrics.NewMetrics(), nil
}

---
dist:
  name: otelcol
  description: "Conf workshop collector"
  output_path: ./dist
  version: v0.0.0-experimental

extensions:
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/basicauthextension v0.80.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.80.0

receivers:
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.80.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/jaegerreceiver v0.80.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/prometheusreceiver v0.80.0
  - gomod: splunk.conf/workshop/example/jenkinscireceiver v0.0.0
    path: ./jenkinscireceiver

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.80.0

exporters:
  - gomod: go.opentelemetry.io/collector/exporter/loggingexporter v0.80.0
  - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.80.0
  - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.80.0

# This replace is a go directive that allows for redefine
# where to fetch the code to use since the default would be from a remote project.
replaces:
- splunk.conf/workshop/example/jenkinscireceiver => ./jenkinscireceiver

├── build-config.yaml
└── jenkinscireceiver
    ├── go.mod
    ├── config.go
    ├── factory.go
    ├── scraper.go
    └── internal
      └── metadata

これらのファイルを期待される内容でプロジェクトに書き込んだら、go mod tidy を実行します。これにより、すべてのリモート依存関係がフェッチされ、go.mod が更新され、go.sum ファイルが生成されます。

OpenTelemetry Collector 開発

ビジネスロジックの構築

この時点で、現在何もしないカスタムコンポーネントがあるため、Jenkins からこのデータをキャプチャするために必要なロジックを追加する必要があります。

ここから、実行する必要があるステップは以下の通りです

Jenkins に接続するクライアントを作成する
設定されたすべてのジョブをキャプチャする
設定されたジョブの最後のビルドのステータスを報告する
コミットのタイムスタンプとジョブ完了の時間差を計算する

変更は scraper.go に対して行われます。

Jenkins サーバーに接続できるようにするために、“github.com/yosida95/golang-jenkins” パッケージを使用します。このパッケージは、Jenkins サーバーからデータを読み取るために必要な機能を提供します。

次に、“go.opentelemetry.io/collector/receiver/scraperhelper” ライブラリのヘルパー関数を利用して、コンポーネントの起動が完了した後に Jenkins サーバーに接続できるように start 関数を作成します。

package jenkinscireceiver

import (
    "context"

    jenkins "github.com/yosida95/golang-jenkins"
    "go.opentelemetry.io/collector/component"
    "go.opentelemetry.io/collector/pdata/pmetric"
    "go.opentelemetry.io/collector/receiver"
    "go.opentelemetry.io/collector/receiver/scraperhelper"

    "splunk.conf/workshop/example/jenkinscireceiver/internal/metadata"
)

type scraper struct {
    mb     *metadata.MetricsBuilder
    client *jenkins.Jenkins
}

func newScraper(cfg *Config, set receiver.CreateSettings) (scraperhelper.Scraper, error) {
    s := &scraper{
        mb : metadata.NewMetricsBuilder(cfg.MetricsBuilderConfig, set),
    }

    return scraperhelper.NewScraper(
        metadata.Type,
        s.scrape,
        scraperhelper.WithStart(func(ctx context.Context, h component.Host) error {
            client, err := cfg.ToClient(h, set.TelemetrySettings)
            if err != nil {
                return err
            }
            // The collector provides a means of injecting authentication
            // on our behalf, so this will ignore the libraries approach
            // and use the configured http client with authentication.
            s.client = jenkins.NewJenkins(nil, cfg.Endpoint)
            s.client.SetHTTPClient(client)
            return nil
        }),
    )
}

func (s scraper) scrape(ctx context.Context) (pmetric.Metrics, error) {
    // To be filled in
    return pmetric.NewMetrics(), nil
}

これで Jenkins レシーバーを初期化するために必要なすべてのセットアップコードが完了しました。

ここからは、入力を待っていた scrape メソッドに焦点を当てます。このメソッドは、設定で構成された間隔（デフォルトでは毎分）で実行されます。

設定されたジョブの数をキャプチャしたい理由は、Jenkins サーバーの成長を確認し、オンボードしたプロジェクトの数を測定できるようにするためです。これを行うために、Jenkins クライアントを呼び出してすべてのジョブをリストし、エラーが報告された場合はメトリクスなしでそれを返し、そうでなければメトリクスビルダーからデータを出力します。

func (s scraper) scrape(ctx context.Context) (pmetric.Metrics, error) {
    jobs, err := s.client.GetJobs()
    if err != nil {
        return pmetric.Metrics{}, err
    }

    // Recording the timestamp to ensure
    // all captured data points within this scrape have the same value.
    now := pcommon.NewTimestampFromTime(time.Now())

    // Casting to an int64 to match the expected type
    s.mb.RecordJenkinsJobsCountDataPoint(now, int64(len(jobs)))

    // To be filled in

    return s.mb.Emit(), nil
}

前のステップでは、すべてのジョブをキャプチャし、ジョブの数を報告することができました。このステップでは、各ジョブを調べ、報告された値を使用してメトリクスをキャプチャします。

func (s scraper) scrape(ctx context.Context) (pmetric.Metrics, error) {
    jobs, err := s.client.GetJobs()
    if err != nil {
        return pmetric.Metrics{}, err
    }

    // Recording the timestamp to ensure
    // all captured data points within this scrape have the same value.
    now := pcommon.NewTimestampFromTime(time.Now())

    // Casting to an int64 to match the expected type
    s.mb.RecordJenkinsJobsCountDataPoint(now, int64(len(jobs)))

    for _, job := range jobs {
        // Ensure we have valid results to start off with
        var (
            build  = job.LastCompletedBuild
            status = metadata.AttributeJobStatusUnknown
        )

        // This will check the result of the job, however,
        // since the only defined attributes are
        // `success`, `failure`, and `unknown`.
        // it is assume that anything did not finish
        // with a success or failure to be an unknown status.

        switch build.Result {
        case "aborted", "not_built", "unstable":
            status = metadata.AttributeJobStatusUnknown
        case "success":
            status = metadata.AttributeJobStatusSuccess
        case "failure":
            status = metadata.AttributeJobStatusFailed
        }

        s.mb.RecordJenkinsJobDurationDataPoint(
            now,
            int64(job.LastCompletedBuild.Duration),
            job.Name,
            status,
        )
    }

    return s.mb.Emit(), nil
}

最後のステップは、コミットからジョブ完了までにかかった時間を計算し、DORA メトリクスを推測するのに役立てることです。

func (s scraper) scrape(ctx context.Context) (pmetric.Metrics, error) {
    jobs, err := s.client.GetJobs()
    if err != nil {
        return pmetric.Metrics{}, err
    }

    // Recording the timestamp to ensure
    // all captured data points within this scrape have the same value.
    now := pcommon.NewTimestampFromTime(time.Now())

    // Casting to an int64 to match the expected type
    s.mb.RecordJenkinsJobsCountDataPoint(now, int64(len(jobs)))

    for _, job := range jobs {
        // Ensure we have valid results to start off with
        var (
            build  = job.LastCompletedBuild
            status = metadata.AttributeJobStatusUnknown
        )

        // Previous step here

        // Ensure that the `ChangeSet` has values
        // set so there is a valid value for us to reference
        if len(build.ChangeSet.Items) == 0 {
            continue
        }

        // Making the assumption that the first changeset
        // item is the most recent change.
        change := build.ChangeSet.Items[0]

        // Record the difference from the build time
        // compared against the change timestamp.
        s.mb.RecordJenkinsJobCommitDeltaDataPoint(
            now,
            int64(build.Timestamp-change.Timestamp),
            job.Name,
            status,
        )
    }

    return s.mb.Emit(), nil
}

これらのステップがすべて完了すると、カスタム Jenkins CI レシーバーの構築が完了です！

次のステップ

コンポーネントから欲しい機能がおそらくもっとあるでしょう。例えば

ジョブが使用したブランチ名を含めることはできますか？
ジョブのプロジェクト名を含めることはできますか？
プロジェクトの累積ジョブ期間をどのように計算しますか？
変更が機能することをどのように検証しますか？

この時間を使って、遊んでみたり、壊してみたり、変更したり、ビルドからログをキャプチャしてみたりしてください。

OpenTelemetry でオブザーバビリティをクラウドネイティブに

概要

Ninja セクション

対象者

前提条件

学習目標

OpenTelemetry アーキテクチャ

OpenTelemetry Collector の基本概念のサブセクション

OpenTelemetry Collector Contrib のインストール

OpenTelemetry Collector Contrib ディストリビューションのダウンロード

OpenTelemetry Collector Contrib ディストリビューションのインストール

1. インストールのサブセクション

OpenTelemetry Collector Contrib のインストール

Collector が動作していることを確認する

なぜ独自の Collector をビルドするのか？

独自の Collector をビルドするメリットは？

Collector をビルドする際の考慮事項は？

Ninja ゾーン

参考資料

デフォルト設定

OpenTelemetry Collector Extensions

2. Extensionsのサブセクション

OpenTelemetry Collector Extensions

Health Check

OpenTelemetry Collector Extensions

Performance Profiler

OpenTelemetry Collector Extensions

zPages

なぜデータをディスクにキューイングするのか？

データをディスクにキューイングする際の考慮事項

参考資料

設定の確認

OpenTelemetry Collector Receivers

3. Receiversのサブセクション

OpenTelemetry Collector Receivers

Host Metrics Receiver

OpenTelemetry Collector Receivers

Prometheus Receiver

ダッシュボード例 - Prometheus メトリクス

OpenTelemetry Collector Receivers

その他の Receiver

何が必要ですか？

考慮すべき事項

Ninja ゾーン

設定の確認

OpenTelemetry Collector Processors

4. Processorsのサブセクション

OpenTelemetry Collector Processors

Batch Processor

OpenTelemetry Collector Processors

Resource Detection Processor

OpenTelemetry Collector Processors

Attributes Processor

processor の代わりに connector を使用する理由

connector に関する考慮事項

参考資料

設定の確認

OpenTelemetry Collector Exporters

5. Exportersのサブセクション

OpenTelemetry Collector Exporters

OTLP HTTP Exporter

設定の確認

OpenTelemetry Collector Service

6. Serviceのサブセクション

OpenTelemetry Collector Service

Hostmetrics Receiver

OpenTelemetry Collector Service

Prometheus Internal Receiver

OpenTelemetry Collector Service

Resource Detection Processor

OpenTelemetry Collector Service

Attributes Processor

OpenTelemetry Collector Service

OTLP HTTP Exporter

なぜ Collector を監視するのか？

考慮事項

Ninja Zone

参考資料

最終設定

データの可視化