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

Mon, 01 Jan 0001 00:00:00 +0000

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

Как это работает
Где задаются шаблоны
Переменные шаблонов
Сбор логов через автообнаружение
Теги контейнера
Включение и исключение контейнеров
Источники шаблонов и слушатели
Проверка работы

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

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

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

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

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

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

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

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

Лейбл	Содержимое
`com.protoobp.ad.checks`	JSON-объект: имя интеграции → `init_config` и `instances`. Рекомендуемый формат
`com.protoobp.ad.check_names`	JSON-список имён интеграций (формат v1, используется вместе с двумя следующими)
`com.protoobp.ad.init_configs`	JSON-список `init_config`, по одному на интеграцию
`com.protoobp.ad.instances`	JSON-список `instances`, по одному на интеграцию
`com.protoobp.ad.logs`	JSON-список источников логов — см. Сбор логов
`com.protoobp.ad.tags`	JSON-список дополнительных тегов — см. Теги контейнера

Пример для 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"}]'

Docker Swarm

В файле стека лейблы указываются в секции labels сервиса, а не в deploy.labels — см. Автообнаружение и теги Swarm.

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

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

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

Аннотация	Содержимое
`ad.protoobp.com/<контейнер>.checks`	JSON-объект: имя интеграции → `init_config` и `instances`. Рекомендуемый формат
`ad.protoobp.com/<контейнер>.check_names`, `.init_configs`, `.instances`	Формат v1, как у лейблов Docker
`ad.protoobp.com/<контейнер>.logs`	Источники логов контейнера

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 указывается он, а не имя образа.

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

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

Переменная	Значение
`%%host%%`	IP-адрес контейнера. Если сетей несколько, берётся адрес в сети `bridge`; если её нет, шаблон не применяется — укажите сеть явно через `%%host_<сеть>%%`
`%%host_<сеть>%%`	IP-адрес контейнера в указанной сети Docker, например `%%host_backend%%`
`%%port%%`	Наибольший из открытых портов контейнера
`%%port_<N>%%`	Порт с индексом `N` в списке открытых портов, отсортированном по возрастанию (`%%port_0%%` — наименьший)
`%%port_<имя>%%`	Порт с указанным именем (имя порта контейнера в Kubernetes, например `%%port_metrics%%`)
`%%pid%%`	PID основного процесса контейнера
`%%hostname%%`	Имя хоста контейнера
`%%env_<ПЕРЕМЕННАЯ>%%`	Значение переменной окружения процесса агента (не контейнера приложения)
`%%kube_namespace%%`	Пространство имён пода
`%%kube_pod_name%%`	Имя пода
`%%kube_pod_uid%%`	UID пода

Если переменную не удалось вычислить (например, у контейнера нет открытых портов, а шаблон использует %%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.

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

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

Параметр	Что исключается
`container_exclude` / `container_include`	Метрики, логи и автообнаружение
`container_exclude_metrics` / `container_include_metrics`	Только метрики контейнера
`container_exclude_logs` / `container_include_logs`	Только логи контейнера
`ac_exclude` / `ac_include`	Метрики и автообнаружение (прежние названия параметров)

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

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) и включает нужные источники шаблонов и слушатели событий. Ручная настройка требуется в редких случаях.

Параметр	Назначение
`config_providers`	Источники шаблонов: `kubelet` (аннотации подов), `docker` (лейблы контейнеров), `clusterchecks` (проверки, распределяемые Cluster Agent), `kube_services` (сервисы Kubernetes), а также внешние хранилища шаблонов `etcd`, `consul`, `zookeeper`
`extra_config_providers`	Дополнительные источники по имени, с параметрами по умолчанию
`listeners`, `extra_listeners`	Слушатели событий контейнеров
`autoconfig_exclude_features`	Отключить автоматически определённую среду, например `["docker"]` на хосте, где Docker установлен, но не используется
`autoconfig_include_features`	Принудительно включить среду, которую агент не определил сам
`autoconf_config_files_poll`, `autoconf_config_files_poll_interval`	Перечитывать файлы `conf.d` без перезапуска агента (только конфигурации интеграций, не логов)

Пример для хоста, где агент установлен пакетом и должен работать с контейнерами 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.

Документация Proto Observability Platform – autodiscovery