Запустіть OBI як контейнер Docker

OBI може запускати автономний контейнер Docker, який може інструментувати процес, що виконується в іншому контейнері.

Образи контейнерів OBI публікуються в обох реєстрах:

• Docker Hub: otel/ebpf-instrument:v<версія>
• GHCR: ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/ebpf-instrument:v<версія>

Теґ розробки також опубліковано на Docker Hub як:

otel/ebpf-instrument:main

Контейнер OBI повинен бути налаштований наступним чином:

• запустіть як привілейований контейнер або як контейнер з можливістю SYS_ADMIN (але цей останній варіант може не працювати в деяких середовищах контейнерів)
• Використовуйте простір імен PID host, щоб дозволити доступ до процесів в інших контейнерах.

Підписання та перевірка образів

Образ контейнера OBI підписується за допомогою Cosign з використанням тимчасових ключів, автентифікованих через протокол OIDC (OpenID Connect) в GitHub Actions. Це забезпечує автентичність та цілісність контейнера, опублікованого проєктом OpenTelemetry.

Ви можете перевірити підпис образу контейнера за допомогою такої команди:

export VERSION=v0.7.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 issuer та регулярний вираз ідентичності, показані вище

Приклад Docker CLI

Для цього прикладу вам потрібен контейнер, що виконує HTTP/S або gRPC сервіс. Якщо у вас його немає, ви можете використовувати цей простий рушій для блогів, написаний на Go:

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

Наведена команда запускає простий HTTPS-застосунок. Процес відкриває внутрішній порт контейнера 8443, який потім експонується на рівні хосту як порт 18443.

Встановіть змінні середовища, щоб налаштувати OBI для виводу в stdout і прослуховування порту (контейнера) для перевірки виконуваного файлу:

export OTEL_EBPF_TRACE_PRINTER=text
export OTEL_EBPF_OPEN_PORT=8443

OBI потрібно запускати з наступними налаштуваннями:

• в режимі --privileged або з можливістю SYS_ADMIN (хоча SYS_ADMIN може не бути достатньо в деяких середовищах контейнерів)
• простір імен PID host, з опцією --pid=host.

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 виводить запити на відстеження у stdout, подібні до:

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