Автообнаружение интеграций в контейнерах

На этой странице:

• Как это работает
• Где задаются шаблоны
  • Лейблы контейнеров Docker
  • Аннотации подов Kubernetes
  • Файлы конфигурации агента
• Переменные шаблонов
• Сбор логов через автообнаружение
• Теги контейнера
• Включение и исключение контейнеров
• Источники шаблонов и слушатели
• Проверка работы

Как это работает

В контейнерной среде адреса и порты сервисов меняются при каждом перезапуске, поэтому статическая конфигурация интеграции с host: 10.0.3.17 быстро устаревает. Автообнаружение решает эту задачу так:

1. Агент отслеживает запуск и остановку контейнеров через Docker, containerd/CRI или kubelet.
2. Для каждого контейнера агент ищет шаблон конфигурации интеграции — в лейблах контейнера, в аннотациях пода или в файлах conf.d.
3. Агент подставляет в шаблон фактические значения (IP-адрес, порт, имя пода — см. переменные шаблонов) и запускает проверку.
4. Когда контейнер останавливается, проверка снимается.

Метрики самих контейнеров (CPU, память, сеть) агент собирает без шаблонов — см. Собираемые контейнерные метрики. Шаблоны нужны для интеграций с приложениями внутри контейнеров: PostgreSQL, Redis, Nginx, JMX и т. д.

Где задаются шаблоны

Шаблон состоит из тех же частей, что и файл интеграции conf.d/<интеграция>.d/conf.yaml: имя интеграции, init_config и список instances. Различается только способ записи.

Лейблы контейнеров Docker

Шаблон указывается в лейблах контейнера с префиксом com.protoobp.ad.:

Пример для Redis в docker-compose.yaml:

services:
  redis:
    image: redis:7
    labels:
      com.protoobp.ad.checks: |
        {
          "redisdb": {
            "init_config": {},
            "instances": [{"host": "%%host%%", "port": "6379"}]
          }
        }        

Тот же шаблон в формате v1:

    labels:
      com.protoobp.ad.check_names: '["redisdb"]'
      com.protoobp.ad.init_configs: '[{}]'
      com.protoobp.ad.instances: '[{"host": "%%host%%", "port": "6379"}]'

Агент также читает лейблы со старым префиксом, которые встречаются в готовых образах сторонних производителей, поэтому такие образы мониторятся без изменений.

Аннотации подов Kubernetes

В Kubernetes шаблон указывается в аннотациях пода (в Deployment, StatefulSet и т. п. — в spec.template.metadata.annotations). В ключ аннотации входит имя контейнера внутри пода:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
spec:
  template:
    metadata:
      annotations:
        ad.protoobp.com/postgres.checks: |
          {
            "postgres": {
              "init_config": {},
              "instances": [
                {
                  "host": "%%host%%",
                  "port": "5432",
                  "username": "protoobp",
                  "password": "ENC[k8s_secret@db/postgres-credentials/password]"
                }
              ]
            }
          }          
    spec:
      containers:
        - name: postgres        # совпадает с <контейнер> в ключе аннотации
          image: postgres:16

Пароль в примере не хранится в манифесте, а берётся из Kubernetes Secret — см. Управление секретами.

Если имя контейнера в аннотации не совпадает ни с одним контейнером пода, шаблон не применяется. Проверить это можно командой protoobp-agent configcheck (см. Проверка работы).

Файлы конфигурации агента

Шаблон можно положить в обычный файл интеграции, добавив в него ad_identifiers — список идентификаторов контейнеров, к которым шаблон применяется. Идентификатор — короткое имя образа без реестра и тега:

# conf.d/redisdb.d/conf.yaml
ad_identifiers:
  - redis              # образы registry.local/library/redis:7, redis:6.2 и т. п.

init_config:

instances:
  - host: "%%host%%"
    port: "6379"

Этот способ удобен, когда менять образы и манифесты приложений нельзя. На Kubernetes файлы передаются агенту через параметр protoobp.confd в values.yaml Helm-чарта.

Отдельный идентификатор можно назначить контейнеру лейблом com.protoobp.ad.check.id — тогда в ad_identifiers указывается он, а не имя образа.

Переменные шаблонов

Значения подставляются при каждом запуске контейнера.

Если переменную не удалось вычислить (например, у контейнера нет открытых портов, а шаблон использует %%port%%), шаблон к контейнеру не применяется, а причина видна в выводе protoobp-agent configcheck.

Подстановку %%env_...%% можно ограничить: ad_allowed_env_vars задаёт список разрешённых переменных, ad_disable_env_var_resolution: true запрещает подстановку полностью.

Сбор логов через автообнаружение

Чтобы агент собирал логи из контейнеров, должны быть включены logs_enabled: true и сбор логов контейнеров (см. Сбор логов контейнеров). Лейбл или аннотация logs задаёт для контейнера source, service и правила обработки:

labels:
  com.protoobp.ad.logs: '[{"source": "nginx", "service": "frontend"}]'

annotations:
  ad.protoobp.com/frontend.logs: '[{"source": "nginx", "service": "frontend"}]'

В той же записи указываются правила log_processing_rules — например, склейка многострочных записей (multi_line) или маскирование данных (mask_sequences, см. Маскирование данных в логах).

Параметр logs_config.container_collect_all: true включает сбор логов всех контейнеров, в том числе без лейблов; лейблы logs в этом случае уточняют source и service.

Теги контейнера

Лейбл com.protoobp.ad.tags добавляет теги ко всем метрикам, логам и трейсам контейнера:

labels:
  com.protoobp.ad.tags: '["team:billing", "env:prod"]'

В Docker Swarm агент дополнительно добавляет теги из стандартных лейблов Swarm — см. Автообнаружение и теги Swarm.

Включение и исключение контейнеров

По умолчанию агент собирает метрики всех контейнеров и применяет шаблоны ко всем контейнерам, для которых они найдены. Фильтры позволяют исключить служебные или шумные контейнеры.

Значение — список правил вида <атрибут>:<регулярное выражение>:

• name: — имя контейнера;
• image: — образ;
• kube_namespace: — пространство имён Kubernetes.

Правила include имеют приоритет над exclude: контейнер, попавший под оба, не исключается.

# Исключить все контейнеры, кроме пространств имён prod и payments
container_exclude: ["name:.*"]
container_include: ["kube_namespace:^prod$", "kube_namespace:^payments$"]

# Не собирать логи sidecar-контейнеров
container_exclude_logs: ["image:.*istio/proxyv2.*", "name:^istio-proxy$"]

Через переменные окружения (POBP_CONTAINER_EXCLUDE, POBP_CONTAINER_INCLUDE и т. д.) правила передаются строкой через пробел. В Helm-чарте агента для этого есть параметры protoobp.containerExclude, protoobp.containerInclude, protoobp.containerExcludeLogs и protoobp.containerExcludeMetrics.

Служебные pause-контейнеры Kubernetes и OpenShift исключаются по умолчанию (exclude_pause_container: true).

Источники шаблонов и слушатели

Обычно ничего настраивать не нужно: агент сам определяет среду (Docker, containerd, Kubernetes, Podman) и включает нужные источники шаблонов и слушатели событий. Ручная настройка требуется в редких случаях.

Пример для хоста, где агент установлен пакетом и должен работать с контейнерами Docker:

listeners:
  - name: docker
config_providers:
  - name: docker
    polling: true

Пользователь pobp-agent при этом должен входить в группу docker — см. Linux агент – конфигурация.

Проверка работы

• protoobp-agent configcheck — список всех применённых конфигураций интеграций с источником каждой (файл, лейбл контейнера, аннотация пода) и подставленными значениями переменных. В конце вывода перечислены шаблоны, которые не удалось применить, с причиной.
• protoobp-agent status — в блоке Collector видно, запускаются ли проверки и есть ли ошибки подключения к сервису.

В контейнере агента команды выполняются как agent configcheck и agent status (см. Проверка работы агента).

Примеры шаблонов для конкретных технологий есть на страницах интеграций, например JMX, Oracle, PostgreSQL, Nginx.