Victoriametrics

Назначение файла

Документ описывает, как устроен каталог config/victoriametrics/deployment/docker/, за что отвечают его файлы и папки, и содержит рекомендации по настройке vmagent, vmalert и alertmanager.

1. Дерево каталогов

config/
└─ victoriametrics/
   └─ deployment/
      └─ docker/
         ├─ .env_example                # пример переменных окружения
         ├─ docker-compose.yml          # основной compose-файл стека VM
         ├─ README.md                   # краткое описание (tl;dr)
         └─ config/                     # вся пользовательская конфигурация
            ├─ exporter/                # prom-yml для vmagent (targets, SD и др.)
            │   └─ prometheus.yml
            ├─ alerts/                  # набор rule-файлов для vmalert
            │   ├─ alerts.yml           # общие алерты VM
            │   ├─ alerts-health.yml    # здоровье стека
            │   ├─ alerts-vmagent.yml   # vmagent-specific
            │   ├─ alerts-vmalert.yml   # vmalert-specific
            │   └─ ...                  # бизнес-алерты (ASU PPK, Mobipass и т.п.)
            └─ alertmanager/            # конфиг AM + go-tmpl шаблоны
                ├─ alertmanager.yml
                └─ template/
                   ├─ email.tmpl
                   └─ telegram.tmpl

2. Переменные окружения (`.env`)

Переменная	Используется сервисом	Назначение
`VMETRICS_HOST` / `VMETRICS_PORT`	victoriametrics	URL, который проксирует Traefik на веб-UI VM (8428)
`VMLOGS_HOST` / `VMLOGS_PORT`	victorialogs	URL для VictoriaLogs
`VMAGENT_HOST` / `VMAGENT_PORT`	vmagent	Web-UI vmagent (8429)
`VMALERT_HOST` / `VMALERT_PORT`	vmalert	Web-UI vmalert (8880)
`ALERT_HOST` / `ALERT_PORT`	alertmanager	Web-UI alertmanager (9093)
`COMPOSE_PROJECT_NAME`	все	уникальный префикс контейнеров (опц.)

Переменные с *_HOST используются мета-данными Traefik для генерации маршрутов HTTPS. Если Traefik выключен — можете опустить эти переменные и раскомментировать секции ports: в compose-файле.

3. Обзор сервисов `docker-compose.yml`

Сервис	Образ	Порт (в контейнере)	Кратко
`vmagent`	`victoriametrics/vmagent`	8429	Собирает метрики, передаёт в VM. Поддерживает Prometheus-compatible scrape + SD.
`victoriametrics`	`victoriametrics/victoria-metrics`	8428	TSDB. Хранит метрики и отвечает на запросы.
`vmalert`	`victoriametrics/vmalert`	8880	Исполняет rule-файлы, шлёт алерты в alertmanager и записи обратно в VM.
`alertmanager`	`prom/alertmanager`	9093	Получает алерты, рассылает согласно `alertmanager.yml`.
`victorialogs`	`victoriametrics/victoria-logs`	9428	Хранение логов.

4. Настройка vmagent

Файл: config/exporter/prometheus.yml

Основные моменты:

Targets / Scrape-configs — каждая секция job_name описывает источник метрик. Для статического списка используйте: ```yaml
job_name: my_service static_configs:
- targets: ['host:port'] ```
Consul SD — пример уже реализован (consul_exporters). Помечайте сервис тегом monitoring в Consul, чтобы он автоматически подцепился.
Remote-write — задаётся в compose-файле флагом --remoteWrite.url. Менять обычно не нужно.
Добавление нового target-а:
Отредактируйте prometheus.yml – добавьте новую секцию либо Consul-тег.
Перезапустите один контейнер vmagent: bash docker compose up -d vmagent

Все изменения конфигурации vmagent подхватываются без полного рестарта стека.

5. Настройка vmalert

vmalert загружает все файлы config/alerts/*.yml по маске --rule=/etc/alerts/*.yml.

5.1 Структура rule-файла

- alert: Название
  expr: <PromQL-выражение>
  for: 5m            # опционально – время срабатывания
  labels:
    severity: warning   # critical | info
    repeat_freq: 1h     # наша кастомная метка — период повторения
  annotations:
    summary: "Короткий заголовок"
    description: "Развёрнутое описание"
    alertReferance: "Инструкция для ОТП / ОЭ"

5.2 Добавление/изменение правил

Создайте новый .yml или отредактируйте существующий в config/alerts/.
Старайтесь группировать по «домену» (пример: alerts-mobipass.yml).
Перезапустите только vmalert: docker compose up -d vmalert — он перечитает правила.
Проверить статус можно в веб-UI vmalert (/groups).

В Grafana при клике на алерт ссылка Explore открывает выражение автоматически – это обеспечено флагом --external.alert.source в compose-файле.

6. Настройка Alertmanager

Файл: config/alertmanager/alertmanager.yml

Ключевые блоки:

route — дерево маршрутизации алертов. Самый верхний receiver: blackhole заглушает всё, а вложенные routes: переопределяют.
matchers — вместо устаревших match используются label=value|~"regex".
receivers — email / telegram / webhook и т.д.
templates — HTML-/Telegram-шаблоны в template/.

6.1 Добавление нового канала уведомлений

Создайте секцию в receivers: (пример для Slack, Opsgenie и т.д.).
Добавьте ветку в routes: с необходимыми matchers.
Перезапустите alertmanager: bash docker compose up -d alertmanager

6.2 Безопасность секретов

Чувствительные токены/пароли храните в переменных окружения или Docker secrets, а в alertmanager.yml используйте формат ${ENV_VAR}.

7. VictoriaLogs — сбор и хранение логов

victorialogs — это компонент для централизованного хранения и поиска логов, основанный на движке VictoriaMetrics. Он уже включён в docker-compose.yml и работает как отдельный контейнер.

Образ: victoriametrics/victoria-logs:latest
Порт в контейнере: 9428 (HTTP API и UI)
Данные хранятся в томе vldata и пути /vlogs внутри контейнера.

7.1 Инжест логов

VM Native. Любой агент (Vector, Fluent Bit, Filebeat) может слать логи через HTTP POST в формате: bash curl -X POST "http://victorialogs:9428/insert/jsonline?stream=myapp" \ --data-binary '{"ts":"2024-01-02T15:04:05Z","level":"info","msg":"hello"}'
Promtail-совместимый. Можно отправлять логи через API совместимое с Loki (/loki/api/v1/push).
Syslog. Включается параметром --syslogListenAddr=:514 (добавьте в compose, если нужен).

7.2 Чтение логов

Веб-UI доступен по адресу https://<VMLOGS_HOST>.
Query-синтаксис похож на PromQL, пример: {stream="myapp"} |~ "error|warn"
Grafana datasource «VictoriaLogs» уже настроен в datasource.yml, поэтому в дашбордах можно строить графики по логам.

7.3 Настройки контейнера

Если требуется изменить путь данных или параметры слушающих портов, отредактируйте секцию victorialogs в docker-compose.yml, например:

command:
  - "--storageDataPath=/vlogs"
  - "--httpListenAddr=:9428"
  - "--retentionPeriod=3"

7.4 Бэкап логов

# пример резервного копирования тома vldata
docker run --rm -v vldata:/data -v $(pwd):/backup alpine \
  tar czf /backup/vlogs_backup_$(date +%F).tgz -C /data .

8. Запуск стека

cd config/victoriametrics/deployment/docker
cp .env_example .env   # заполните переменные
# при необходимости создайте сеть
# docker network create monitoring_net

docker compose up -d   # запустятся все контейнеры

Проверки:

URL	Описание
`https://<VMETRICS_HOST>`	веб-UI VictoriaMetrics
`https://<VMAGENT_HOST>`	статус vmagent
`https://<VMALERT_HOST>`	статус vmalert / активные алерты
`https://<ALERT_HOST>`	Alertmanager
`https://<VMLOGS_HOST>`	VictoriaLogs UI