Docker: Настройка Promtail для агрегации логов в Loki

Введение

Добро пожаловать в этот практический лабораторный практикум по конфигурации Loki. Loki — это горизонтально масштабируемая, высокодоступная, мультиарендная система агрегации логов, вдохновленная Prometheus. Она разработана, чтобы быть очень экономичной и простой в эксплуатации.

В этом практикуме мы сосредоточимся на полном базовом рабочем процессе сбора и просмотра логов. Мы будем использовать три ключевых компонента:

Loki: Основной сервер, отвечающий за хранение и обработку логов.
Promtail: Агент, который обнаруживает локальные файлы логов и отправляет их в экземпляр Loki.
Grafana: Платформа визуализации, к которой мы подключимся через Loki для исследования и запроса наших логов.

Вы самостоятельно загрузите и запустите Loki и Grafana, настроите Promtail и просмотрите логи в Grafana. Ход загрузки виден в Terminal, а неудачную загрузку можно повторить.

Поддержка Promtail завершилась 2 марта 2026 года. Он сохранён в этой работе для изучения существующих развёртываний Promtail; для новых сборщиков логов в рабочей среде используйте Grafana Alloy.

Загрузка образов и запуск Loki и Grafana

На этом шаге вы подготовите службы журналирования перед настройкой сборщика. Loki хранит логи, Grafana запрашивает их, а Promtail отправляет локальные файлы в Loki. Инициализация не загружает и не запускает эти службы.

cd /home/labex/project

Каждый фиксированный тег задаёт версию, используемую в этой лабораторной работе. Загрузка может занять несколько минут. Дождитесь возврата приглашения после каждой команды. При ошибке повторите ту же команду pull: Docker повторно использует готовые слои. Не продолжайте, пока загрузка не завершена.

docker pull grafana/loki:3.5.0

docker pull grafana/grafana:11.6.0

docker pull grafana/promtail:3.5.0

docker network create создаёт сеть, в которой контейнеры могут разрешать имена друг друга. docker run -d запускает контейнер в фоне; --name задаёт имя, --network подключает к сети, а -p связывает порт хоста с портом контейнера. Для Grafana используйте порт хоста 8080, чтобы избежать конфликта со службами платформы на порту 3000. Loki использует стандартную конфигурацию одного экземпляра из своего образа.

docker network create monitoring-net

docker run -d --name loki --network monitoring-net -p 3100:3100 grafana/loki:3.5.0

docker run -d --name grafana --network monitoring-net -p 8080:3000 grafana/grafana:11.6.0

Параметры curl сообщают об ошибках HTTP и повторяют запрос при временных ошибках запуска до 30 раз с интервалом две секунды. Работающий контейнер ещё может инициализироваться, поэтому дождитесь успешной проверки состояния. Пока ingester Loki инициализируется, служба может возвращать HTTP 503.

curl --fail --silent --show-error --retry 30 --retry-delay 2 --retry-connrefused --retry-all-errors http://localhost:3100/ready

curl --fail --silent --show-error --retry 30 --retry-delay 2 --retry-connrefused --retry-all-errors http://localhost:8080/api/health

Продолжайте, только когда Loki вернёт ready, а Grafana сообщит "database": "ok". Если служба не готова, сначала проверьте docker ps -a и логи контейнера, например командой docker logs grafana.

Создание promtail.yml для сбора системных логов

На этом шаге вы создадите конфигурационный файл для Promtail. Этот YAML-файл указывает Promtail, где находится сервер Loki и какие файлы логов ему следует отслеживать. Вся ваша работа должна выполняться в директории ~/project.

Сначала создайте новый файл с именем promtail.yml с помощью редактора nano.

nano promtail.yml

Теперь скопируйте и вставьте следующую конфигурацию в редактор nano.

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: varlogs
    static_configs:
      - targets:
          - localhost
        labels:
          job: varlogs
          __path__: /var/log/*.log

Давайте разберем эту конфигурацию:

server: Настраивает собственный веб-сервер Promtail, который не используется в этом практикуме.
positions: Указывает файл, в котором Promtail записывает последнее прочитанное местоположение в каждом файле логов, чтобы избежать повторной отправки старых логов при перезапуске.
clients: Определяет адрес экземпляра Loki. Мы используем http://loki:3100, потому что и Promtail, и Loki будут работать в одной сети Docker, а loki — это имя контейнера.
scrape_configs: Это основная секция. Мы определяем job с именем varlogs, который собирает (scrapes) все файлы, оканчивающиеся на .log в директории /var/log/.

После вставки содержимого сохраните файл и выйдите из nano, нажав Ctrl+X, затем Y и, наконец, Enter.

Запуск контейнера Promtail с указанием Loki

На этом шаге вы запустите контейнер Promtail, используя конфигурационный файл, который вы только что создали. Команда смонтирует как ваш конфигурационный файл, так и директорию логов хоста внутрь контейнера.

Выполните следующую команду docker run, чтобы запустить Promtail:

docker run -d --name promtail --network monitoring-net -v $(pwd)/promtail.yml:/etc/promtail/config.yml -v /var/log:/var/log grafana/promtail:3.5.0 -config.file=/etc/promtail/config.yml

Вот объяснение флагов команды:

-d: Запускает контейнер в фоновом (detached) режиме.
--name promtail: Присваивает контейнеру имя для удобства обращения.
--network monitoring-net: Подключает контейнер к той же сети, что и Loki и Grafana.
-v $(pwd)/promtail.yml:/etc/promtail/config.yml: Монтирует ваш локальный promtail.yml внутрь контейнера в ожидаемое расположение.
-v /var/log:/var/log: Монтирует директорию /var/log хоста внутрь контейнера, чтобы Promtail мог читать файлы логов.
-config.file=/etc/promtail/config.yml: Указывает процессу Promtail внутри контейнера, какой конфигурационный файл использовать.

После выполнения команды Docker выведет уникальный ID нового контейнера. Вы можете проверить, что контейнер запущен, с помощью команды docker ps.

docker ps

В списке запущенных контейнеров вы должны увидеть promtail, loki и grafana.

После запуска сборщика запишите новое тестовое сообщение. printf выводит сообщение, а sudo tee -a добавляет его в принадлежащий root файл журнала. Параметр -a сохраняет существующие записи.

printf 'labex test message\n' | sudo tee -a /var/log/test.log

Promtail обнаружит файл и отправит сообщение в Loki. Подождите несколько секунд до отправки первого пакета. Порт 9080 используется внутри Promtail; команда не публикует его на VM.

Добавление Loki как источника данных в Grafana

На этом шаге вы подключите Grafana к запущенной вами службе Loki.

После успешных проверок состояния выберите вкладку лаборатории Grafana. Если встроенный вход заблокирован, используйте элемент открытия в браузере. Войдите с именем пользователя admin и паролем admin, затем нажмите Skip на экране смены пароля. Эти данные предназначены только для временной лабораторной среды.

Откройте Connections → Data sources, нажмите Add data source и выберите Loki. Укажите Loki в поле Name. В разделе Connection задайте URL:

http://loki:3100

Имя хоста loki разрешается внутри общей сети Docker, поэтому Grafana может обращаться к Loki напрямую. Браузеру не требуется разрешать это имя контейнера.

Нажмите Save & test. Дождитесь сообщения Data source successfully connected. перед продолжением. Оно подтверждает, что Grafana может запрашивать Loki.

Выполнение базовых запросов логов в представлении Grafana Explore

На этом заключительном шаге вы будете использовать представление "Explore" (Исследование) в Grafana для выполнения простого запроса и просмотра логов, которые Promtail отправляет из вашей среды.

В интерфейсе Grafana перейдите к боковой панели слева и нажмите на значок компаса (Explore).
В левом верхнем углу страницы Explore вы увидите выпадающее меню для выбора источника данных. Если он еще не выбран, выберите Loki.
Вы увидите поле ввода "Log browser" (Просмотр логов). Здесь вы пишете ваши LogQL запросы.
Нажмите кнопку "Code", чтобы переключиться в редактор кода.
Введите следующий запрос в поле ввода:

{job="varlogs"}

Этот LogQL запрос выбирает все потоки логов, у которых метка (label) job имеет значение varlogs. Мы определили эту метку в нашем файле promtail.yml. 6. Нажмите Shift+Enter или синюю кнопку Run query (Выполнить запрос) в правой части экрана.

После выполнения запроса в основной панели под редактором запросов должны появиться строки логов. Вы увидите логи из различных файлов в /var/log. Это подтверждает, что Promtail успешно собирает логи и отправляет их в Loki, а Grafana может их запрашивать.

Общий запрос может вернуть множество системных сообщений. Чтобы найти записанное вами сообщение, добавьте строковый фильтр LogQL |=. Он оставляет строки, содержащие текст в кавычках:

{job="varlogs"} |= "labex test message"

Ещё раз нажмите Run query. Убедитесь, что в результатах есть labex test message. Это подтверждает совместную работу сборщика, Loki и Grafana.

Резюме

Поздравляем! Вы успешно настроили базовый конвейер логирования (logging pipeline) с использованием Loki, Promtail и Grafana.

В этом практикуме вы узнали, как:

Загружать и запускать Docker-контейнеры для инструментов обработки логов, таких как Promtail.
Создавать конфигурационный файл Promtail для указания сервера Loki и определения заданий по сбору логов (log scraping jobs).
Использовать Docker networking для соединения сервисов (Promtail, Loki и Grafana).
Добавлять Loki в качестве источника данных (data source) в пользовательском интерфейсе Grafana.
Выполнять базовый запрос LogQL в представлении Explore в Grafana для поиска и проверки ваших логов.

Эта настройка является основой мощной, масштабируемой и экономически эффективной системы агрегации логов. Отсюда вы можете перейти к изучению более сложных запросов LogQL, парсинга логов и настройки оповещений (alerts) в Grafana на основе содержимого логов.

Конфигурация Loki