Setup: Имя хоста и теги хоста

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

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

Зачем имя хоста
Как агент определяет имя
Как задать имя явно
- Параметры
- Требования к имени
Имя хоста в Docker и Kubernetes
Смена имени хоста
Проверка
Теги хоста

Зачем имя хоста

Имя хоста — метка host у всех данных, которые отправляет агент: системных метрик, метрик интеграций, трейсов и логов. По нему хост отображается в разделе Инфраструктура > Хосты, по нему связываются метрики хоста и трейсы приложений, работающих на нём, и по нему строятся алерты на хосты.

Поэтому имя должно быть:

уникальным — два хоста с одинаковым именем сливаются в интерфейсе в один;
стабильным — после смены имени хост выглядит как новый, а история остаётся под старым именем.

Как агент определяет имя

Агент перебирает источники по порядку:

№	Источник	Поведение
1	Параметр `hostname`	Если задан и корректен — используется, остальные источники не проверяются
2	Файл из параметра `hostname_file`	Если задан, используется содержимое файла (пробелы и переводы строк по краям отбрасываются); дальше не проверяется
3	Облачные сервисы метаданных	Только на некоторых облачных платформах
4	Полное имя (FQDN) ОС	Только при `hostname_fqdn: true`
5	Контейнерная среда	Агент в контейнере берёт имя ноды у Docker или kubelet — см. ниже; заменяет результат шага 4
6	Короткое имя ОС (`hostname`)	Если на предыдущих шагах имя не найдено

Если ни один источник не дал корректного имени, агент не запускается и пишет в журнал unable to reliably determine the host name (в ранних версиях — Error while getting hostname). Задайте имя явно — см. Как задать имя явно.

Как задать имя явно

Параметры

Параметр	Переменная окружения	Назначение
`hostname`	`POBP_HOSTNAME`	Имя хоста. Имеет наивысший приоритет
`hostname_file`	`POBP_HOSTNAME_FILE`	Путь к файлу с именем; используется, если `hostname` не задан
`hostname_fqdn`	`POBP_HOSTNAME_FQDN`	Использовать полное имя ОС (`host.example.local`) вместо короткого (`host`). По умолчанию `false`
`hostname_trust_uts_namespace`	`POBP_HOSTNAME_TRUST_UTS_NAMESPACE`	Доверять имени, полученному внутри изолированного UTS-пространства (контейнер, systemd-nspawn). Только Linux, по умолчанию `false`

Явное имя в protoobp.yaml:

hostname: db-prod-01.corp.local

Если в инфраструктуре есть хосты с одинаковыми короткими именами в разных доменах (db01.msk.corp и db01.spb.corp), включите hostname_fqdn: true, чтобы имена не совпали.

hostname_file удобен при массовой установке, когда имя хоста заранее записывается в файл системой развёртывания:

hostname_file: /etc/protoobp-agent/hostname

Требования к имени

соответствует RFC 1123: латинские буквы, цифры, дефис и точка; не начинается и не заканчивается дефисом;
не длиннее 255 символов;
не localhost, localhost.localdomain, localhost6.localdomain6, ip6-localhost.

Имя, не прошедшее проверку, отбрасывается, и агент переходит к следующему источнику.

Имя хоста в Docker и Kubernetes

Внутри контейнера системное имя — это идентификатор контейнера, а не хоста, поэтому агент в контейнере определяет имя иначе:

Docker — агент запрашивает имя хоста у Docker. Для этого агенту нужен доступ к сокету Docker (/var/run/docker.sock), как в примерах запуска в Docker.
Kubernetes — агент на ноде берёт имя ноды у kubelet, поэтому хост в интерфейсе совпадает с именем ноды кластера.

Если имя не определяется (например, сокет Docker не смонтирован), задайте его переменной окружения контейнера. В Kubernetes удобно подставить имя ноды:

protoobp:
 env:
 - name: POBP_HOSTNAME
 valueFrom:
 fieldRef:
 fieldPath: spec.nodeName

Смена имени хоста

После смены имени (параметром или переименованием сервера) и перезапуска агента:

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

Проверка

Команда hostname показывает имя, которое агент использует:

sudo protoobp-agent hostname

Источник, из которого получено имя, виден в выводе protoobp-agent status (раздел Hostnames, поле hostname provider). Команды для других платформ — на странице Команды и проверка работы.

Теги хоста

Теги хоста — пары ключ:значение, которые агент добавляет к метрикам и логам своего хоста: команда (team:billing), площадка (dc:msk-1), окружение (env:prod). По ним строятся фильтры, группировки на дашбордах и условия алертов. В хранилище метрик тег становится меткой: team:billing → team="billing".

Включение

Теги задаются двумя параметрами, значения которых объединяются:

Параметр	Переменная окружения	Назначение
`tags`	`POBP_TAGS`	Основной список тегов
`extra_tags`	`POBP_EXTRA_TAGS`	Дополнительные теги — удобно, когда `tags` задан в файле, а часть тегов добавляется переменной окружения при развёртывании

Обязательный параметр

Агент добавляет теги хоста к данным только в течение срока expected_tags_duration после своего запуска (для логов — logs_config.expected_tags_duration). По умолчанию срок равен нулю, и без этих параметров теги хоста не попадают ни в метрики, ни в логи. Задайте срок, заведомо больший, чем время непрерывной работы агента, например 10 лет (87600h); отсчёт начинается заново при каждом перезапуске агента.

# protoobp.yaml
tags:
 - team:billing
 - dc:msk-1
expected_tags_duration: 87600h  # теги к метрикам
logs_config:
 expected_tags_duration: 87600h  # теги к логам

Через переменные окружения (Docker, Kubernetes):

POBP_TAGS="team:billing dc:msk-1"
POBP_EXPECTED_TAGS_DURATION=87600h
POBP_LOGS_CONFIG_EXPECTED_TAGS_DURATION=87600h

В Helm-чарте агента теги задаются параметром protoobp.tags, а сроки — переменными в protoobp.env:

protoobp:
 tags:
 - team:billing
 env:
 - name: POBP_EXPECTED_TAGS_DURATION
 value: "87600h"
 - name: POBP_LOGS_CONFIG_EXPECTED_TAGS_DURATION
 value: "87600h"

После изменения перезапустите агента.

Параметр env (переменная POBP_ENV) задаёт окружение по умолчанию для трейсов, если трейсер не передал своё. Теги отдельных трейсов задаются в настройках трейсера — см. Конвенция наименования тегов.

Что учесть

Новые временные ряды. Набор меток метрики меняется, поэтому после включения тегов у каждой метрики хоста начинается новый временной ряд, а старый перестаёт обновляться. На графиках за период включения возможен «разрыв» или удвоение линии, если запрос не агрегирует по меткам. То же происходит при каждом изменении или удалении тега.
Метки у алертов. Теги хоста попадают и в метки сработавших алертов по метрикам хоста — их можно использовать в маршрутизации уведомлений.
Кардинальность. Используйте теги с небольшим числом значений (команда, площадка, окружение). Уникальные значения (идентификаторы, время) многократно увеличивают число рядов в хранилище.
Имена ключей. Используйте строчные латинские буквы, цифры и _; ключи не должны совпадать с метками, которые агент добавляет сам (host, service, env, kube_*, container_*).
Теги контейнеров и интеграций. Теги для отдельного контейнера задаются лейблом com.protoobp.ad.tags (см. Автообнаружение), для отдельной интеграции — параметром tags в её instances. Для них expected_tags_duration не нужен.
host_aliases. Параметр принимается агентом, но бэкенд ProtoOBP псевдонимы хостов не использует.

Проверка тегов

Убедитесь, что агент видит параметры: sudo protoobp-agent config | grep -E -A3 '^(tags|extra_tags|expected_tags_duration):'.
Через 2–3 минуты после перезапуска найдите метрику хоста с тегом в браузере метрик, например system_load_1{host="<имя хоста>", team="billing"}.
Для логов: в Logs Explorer теги хоста видны в поле pobptags записей с этого хоста.

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