DockerコンテナとしてOBIを実行する

OBIは、スタンドアロンのDockerコンテナとして実行し、別のコンテナで実行されているプロセスを計装できます。

OBIのコンテナイメージは、以下の両方のレジストリに公開されています。

• Docker Hub: otel/ebpf-instrument:v<version>
• GHCR: ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/ebpf-instrument:v<version>

開発タグは Docker Hub にも以下の名前で公開されています。

otel/ebpf-instrument:main

OBIコンテナは、次のように構成する必要があります。

• 特権コンテナとして実行するか、SYS_ADMIN ケーパビリティを持つコンテナとして実行します(ただし、この最後のオプションは一部のコンテナ環境では機能しない場合があります)。
• host PID名前空間を使用して、他のコンテナ内のプロセスにアクセスできるようにします。

イメージの署名と検証

OBIコンテナイメージは、GitHub Actions の OIDC（OpenID Connect）プロトコルで認証されたエフェメラルキーを使用して、Cosign で署名されています。 これにより、OpenTelemetry プロジェクトが公開したコンテナの真正性と完全性が保証されます。

以下のコマンドを使用して、コンテナイメージの署名を検証できます。

export VERSION=v0.9.0

# Docker Hub のリリースイメージを検証する
cosign verify --certificate-identity-regexp 'https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/' --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' otel/ebpf-instrument:${VERSION}

# GHCR の同じリリースを検証する
cosign verify --certificate-identity-regexp 'https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/' --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/ebpf-instrument:${VERSION}

出力例を以下に示します。

Verification for index.docker.io/otel/ebpf-instrument:main --
The following checks were performed on each of these signatures:
  - The cosign claims were validated
  - Existence of the claims in the transparency log was verified offline
  - The code-signing certificate was verified using trusted certificate authority certificates

[{"critical":{"identity":{"docker-reference":"index.docker.io/otel/ebpf-instrument:main"},"image":{"docker-manifest-digest":"sha256:55426a2bbb8003573a961697888aa770a1f5f67fcda2276dc2187d1faf7181fe"},"type":"https://sigstore.dev/cosign/sign/v1"},"optional":{}}]

検証が成功すると、Cosign のクレームが検証されたことと署名されたイメージダイジェストが表示されます。 検証が失敗した場合は、以下を確認してください。

• クエリしたレジストリにタグが存在するか確認する
• main だけでなく、公開されたリリースタグを検証していることを確認する
• 上記に示された GitHub OIDC 発行者と ID 正規表現を使用していることを確認する

Docker CLIの例

この例では、HTTP/SまたはgRPCサービスを実行しているコンテナが必要です。 コンテナがない場合は、Goで書かれたシンプルなブログエンジンサービスを使用できます。

export VERSION=v0.9.0
docker run -p 18443:8443 --name goblog mariomac/goblog:dev

上記のコマンドは、シンプルなHTTPSアプリケーションを実行します。 このプロセスはコンテナの内部ポート8443を開き、ホストレベルではポート18443として公開されます。

環境変数を設定し、OBIが標準出力に出力し、実行可能ファイルを検査するようにポート(コンテナ)をリッスンするように構成します。

export OTEL_EBPF_TRACE_PRINTER=text
export OTEL_EBPF_OPEN_PORT=8443

OBIは次の設定で実行する必要があります。

• --privileged モード、または SYS_ADMIN ケーパビリティ(ただし、一部のコンテナ環境では SYS_ADMIN だけでは特権が不十分な場合があります)
• --pid=host オプションを使用したホストのPID名前空間を使用

docker run --rm \
  -e OTEL_EBPF_OPEN_PORT=8443 \
  -e OTEL_EBPF_TRACE_PRINTER=text \
  --pid=host \
  --privileged \
  otel/ebpf-instrument:${VERSION}

OBIの実行後、ブラウザで https://localhost:18443 を開き、アプリを使用してテストデータを生成し、OBIが標準出力に次のようなトレースリクエストを出力することを確認します。

time=2023-05-22T14:03:42.402Z level=INFO msg="creating instrumentation pipeline"
time=2023-05-22T14:03:42.526Z level=INFO msg="Starting main node"
2023-05-22 14:03:53.5222353 (19.066625ms[942.583µs]) 200 GET / [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (355.792µs[321.75µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (170.958µs[142.916µs]) 200 GET /static/img.png [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (7.243667ms[295.292µs]) 200 GET /entry/201710281345_instructions.md [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (115µs[75.625µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B

これで、OBIがターゲットのHTTPサービスをトレースするようになったので、OpenTelemetryエンドポイントにメトリクスとトレースを送信するか、Prometheusでメトリクスをスクレイプするように構成します。

トレースとメトリクスをエクスポートする方法については、構成オプションのドキュメントを参照してください。

Docker Composeの例

次のDocker composeファイルは、Docker CLIの例と同じ機能を再現します。

version: '3.8'

services:
  # 計装するサービス。
  # 計装したい他のコンテナに変更してください。
  goblog:
    image: mariomac/goblog:dev
    ports:
      # 18843ポートを公開し、コンテナポート8443に転送します
      - '18443:8443'

  autoinstrumenter:
    image: otel/ebpf-instrument:main
    pid: 'host'
    privileged: true
    environment:
      OTEL_EBPF_TRACE_PRINTER: text
      OTEL_EBPF_OPEN_PORT: 8443

次のコマンドでDocker composeファイルを実行し、アプリを使用してトレースを生成します。

docker compose -f compose-example.yml up