Розгортаємо стек Loki, Promtail та Grafana на Linux

Метрики допомагають оцінити загальний стан та продуктивність інфраструктури, проте для глибокого аналізу інцидентів і розуміння реального стану системи у реальному часі необхідні детальні записи подій. Коли проєкт масштабується, переглядати файли вручну на кожному окремому сервері стає неефективно. Саме для вирішення цієї проблеми в сучасних інфраструктурах впроваджують централізоване логування.

У цьому гайді ми розглянемо розгортання інструменту від Grafana Labs. Ми виконаємо покрокове налаштування Loki, налаштуємо агент Promtail та об’єднаємо все у зручні дашборди.

Навіщо потрібен моніторинг логів в IT-інфраструктурі?

Традиційний підхід із переглядом текстових файлів через tail -f або less працює доти, доки у вас один-два сервери. Якщо ж архітектура складається з десятків хостів або мікросервісів, такий підхід перетворюється на квест.

Сучасний моніторинг логів вирішує три головні завдання:

• всі дані збираються в одному захищеному місці, навіть якщо сам сервер або контейнер, який генерував логи, було видалено.
• замість підключення до кожного хоста через SSH, інженер виконує пошук потрібного запису за секунди в одному вікні.
• на відміну від важкого Elasticsearch, стек Loki Promtail Grafana не індексує весь текст повідомлень, а лише метадані. Це знижує вимоги до оперативної пам’яті та дискового простору в рази.

Як взаємодіють компоненти (PLG Stack)

Щоб побудувати надійну систему, нам знадобляться три компоненти, які разом утворюють так званий стек PLG (Promtail-Loki-Grafana):

1. Promtail (Агент-збирач)
   Встановлюється на кожному цільовому сервері, де генеруються логи. Він підписується на потрібні файли (наприклад, /var/log/syslog або логи Nginx), зчитує нові рядки, додає до них метадані (наприклад, env="production", job="nginx") і відправляє пакетами у Loki.
2. Loki (Сховище)
   Це серце нашої системи. Його часто називають «Prometheus, але для логів». Loki приймає потоки даних від Promtail, зберігає їх у стиснутому вигляді (чанками) на диску та індексує лише ті самі метадані (лейбли), які додав агент.
3. Grafana (Візуалізація)
   Вебпанель, яка підключається до Loki як до джерела даних. Вона дозволяє робити гнучкі запити, будувати графіки інтенсивності помилок та читати логи в реальному часі за допомогою мови LogQL.

Крок 1. Підготовка інфраструктури та мережі

Для підготовки демонстраційного стенда нам знадобиться сервер під керуванням Ubuntu OS (22.04 або 24.04 LTS). У реальних проєктах це може бути як віртуальна машина в хмарі (AWS EC2, DigitalOcean), так і локальний сервер.

Перед тим як підключатися до сервера, необхідно налаштувати мережеві доступи (файрвол системи або Security Groups у хмарі). Для коректної роботи нашого майбутнього стеку мають бути відкриті такі порти:

• Port 3000 (TCP) — для доступу до вебпанелі Grafana.
• Port 3100 (TCP) — внутрішній або зовнішній порт для API-інтерфейсу сховища Loki, куди агенти будуть надсилати логи.

Після перевірки портів підключіться до вашого сервера через SSH:

ssh user@your_server_ip 

Крок 2. Встановлення та запуск Grafana

Ми не будемо використовувати застарілі deb-пакети вручну, а додамо офіційний стабільний репозиторій Grafana Labs. Це гарантує, що система отримуватиме своєчасні оновлення безпеки.

Виконайте в терміналі послідовно такі команди:

# 1. Оновлюємо індекси локальних пакетів та встановлюємо необхідні утиліти
sudo apt update && sudo apt install -y software-properties-common wget 

# 2. Імпортуємо офіційний GPG-ключ для верифікації автентичності пакетів
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add - 

# 3. Додаємо стабільний APT-репозиторій Grafana у систему
sudo add-apt-repository "deb https://packages.grafana.com/oss/deb stable main" 

# 4. Ще раз оновлюємо списки пакетів з урахуванням нового репозиторію
sudo apt update 

# 5. Встановлюємо безпосередньо Grafana OSS
sudo apt install -y grafana

Керування сервісом через systemd

Після встановлення утиліта автоматично створює системну службу, але не запускає її. Нам потрібно додати Grafana в автозавантаження, щоб вона запускалася сама після перезавантаження сервера, та увімкнути її прямо зараз:

# Додаємо службу в автозапуск системи
sudo systemctl enable grafana-server 

# Запускаємо процес Grafana
sudo systemctl start grafana-server 

Щоб переконатися, що все пройшло гладко і процес працює без помилок, виконайте: 

sudo systemctl status grafana-server

У виводі ви маєте побачити зелений статус active (running).

Перша авторизація

Тепер відкрийте браузер і перейдіть за адресою:

http://<IP_вашого_сервера>:3000.

Перед вами з’явиться вікно авторизації Grafana. Там встановлюють такі дані для першого входу:

• Username: admin
• Password: admin

Одразу після натискання кнопки «Log in» система в обов’язковому порядку попросить вас ввести новий, складний пароль. Не ігноруйте цей крок, навіть якщо це тестовий стенд.

Тепер переходимо до самого серця нашої системи — розгортання сховища логів.

Крок 3. Покрокове налаштування Loki

На відміну від багатьох складних інструментів, які вимагають встановлення важких залежностей, Java-середовищ або баз даних, Loki постачається у вигляді вже скомпільованого бінарного файлу (binary). 

Це робить його архітектуру неймовірно простою, а процес встановлення зводиться до завантаження файлу, створення базового конфігу та реєстрації служби в системі.

1. Завантаження та підготовка бінарного файлу

Ми завантажимо стабільну версію Loki безпосередньо з офіційного репозиторію Grafana Labs на GitHub:

# Визначаємо версію та завантажуємо zip-архів з бінарником
LOKI_VERSION="2.8.2" wget https://github.com/grafana/loki/releases/download/v${LOKI_VERSION}/loki-linux-amd64.zip 

# Встановлюємо утиліту unzip (якщо її немає) та розпаковуємо архів
sudo apt-get install -y unzip unzip loki-linux-amd64.zip 

# Переносимо розпакований файл у загальносистемну директорію для бінарників
sudo mv loki-linux-amd64 /usr/local/bin/loki # Надаємо файлу права на виконання sudo chmod +x /usr/local/bin/loki

2. Створення конфігураційного файлу

Loki не працюватиме без файлу конфігурації, де вказано, куди саме зберігати лог-чанки, які ліміти використовувати та на якому порту слухати мережу.

Створимо виділену директорію /etc/loki та завантажимо туди офіційний базовий шаблон конфігурації, який ідеально підходить для запуску на одному сервері (monolithic mode):

# Створюємо папку для конфігураційних файлів
sudo mkdir -p /etc/loki 

# Завантажуємо дефолтний конфіг
loki-local-config.yaml wget https://raw.githubusercontent.com/grafana/loki/v${LOKI_VERSION}/cmd/loki/loki-local-config.yaml -O /etc/loki/local-config.yaml

Цей конфіг налаштований так, щоб зберігати логи локально на диску в директорії /tmp/loki/. Для тестового або демонстраційного стенда цього більш ніж достатньо.

3. Створення системної служби в systemd

Щоб Loki працював у фоновому режимі, автоматично запускався після перезавантаження сервера та правильно перезапускався у разі якихось збоїв, ми оформимо його як системний сервіс (демона).

Створимо новий юніт-файл служби:

sudo tee /etc/systemd/system/loki.service > /dev/null <<EOF 
[Unit] 
Description=Loki Service 
After=network.target 

[Service] 
Type=simple 
ExecStart=/usr/local/bin/loki -config.file=/etc/loki/local-config.yaml 
Restart=on-failure 
RestartSec=5 

[Install] 
WantedBy=multi-user.target 
EOF

4. Ініціалізація та запуск сховища

Тепер, коли система знає про нову службу, нам потрібно оновити конфігурацію манагера системних служб systemd, активувати автозапуск і дати команду на старт:

# Перечитуємо конфігурацію systemd, щоб система побачила новий loki.service
sudo systemctl daemon-reload

# Додаємо Loki в автозапуск
sudo systemctl enable loki

# Запускаємо процес сховища
sudo systemctl start loki

Перевіряємо, чи запустився наш сервіс без помилок:

sudo systemctl status loki 

У терміналі ви маєте побачити знайомий зелений статус active (running). Це означає, що Loki успішно піднявся на порту 3100 і готовий приймати потоки даних. 

Крок 4. Конфігурація Promtail для збору системних логів

Promtail виконує роль кур’єра. Він працює як локальний демон, стежить за оновленнями у вказаних файлах, маркує нові рядки потрібними метаданими (лейблами) і відправляє їх в API Loki. Встановлюється він так само просто, як і попередній компонент.

1. Завантаження та підготовка бінарного файлу Promtail

Завантажимо версію агента, яка сумісна з нашою версією Loki:

# Завантажуємо zip-архів Promtail з GitHub

PROMTAIL_VERSION="2.8.2"

wget https://github.com/grafana/loki/releases/download/v${PROMTAIL_VERSION}/promtail-linux-amd64.zip

# Розпаковуємо архів та переносимо бінарник у системну директорію

unzip promtail-linux-amd64.zip

sudo mv promtail-linux-amd64 /usr/local/bin/promtail

sudo chmod +x /usr/local/bin/promtail

# Створюємо директорії для конфігурації та службових файлів позицій

sudo mkdir -p /etc/promtail

sudo mkdir -p /var/lib/promtail

2. Створення файлу конфігурації

Тепер створимо конфігураційний файл /etc/promtail/promtail-config.yaml. Цей конфіг розділений на кілька логічних блоків: server (внутрішній порт агента), positions (файл, де Promtail записує, на якому рядку файлу він зупинився, щоб не читати все спочатку після перезапуску), clients (куди слати дані) та scrape_configs (що саме збирати).

Ми налаштуємо дві джоби (jobs): перша збиратиме абсолютно всі файли з розширенням .log із директорії /var/log/, а друга — зчитуватиме системний журнал systemd-journal.

Виконайте команду для створення конфігу:

sudo tee /etc/promtail/promtail-config.yaml > /dev/null <<EOF

server:

  http_listen_port: 9080

  grpc_listen_port: 0

positions:

  filename: /var/lib/promtail/positions.yaml

clients:

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

scrape_configs:

  - job_name: system

    static_configs:

      - targets:

          - localhost

        labels:

          job: varlogs

          __path__: /var/log/**/*.log

  - job_name: journal

    journal:

      max_age: 12h

      path: /var/log/journal

      labels:

        job: systemd-journal

    relabel_configs:

      - source_labels: ['__journal__systemd_unit']

        target_label: 'unit'

EOF

Зверніть увагу на параметр clients.url. Наразі там вказано localhost, оскільки наш агент Promtail і сховище Loki розгорнуті на одному й тому самому сервері. 

Якщо у майбутньому ви підключатимете інші сервери інфраструктури, то на тих віддалених машинах у цьому полі потрібно буде вказати реальну IP-адресу або доменне ім’я центрального сервера з Loki.

3. Налаштування прав доступу та служби systemd

Оскільки Promtail повинен мати право читати системні логи (які часто закриті для звичайних користувачів), ми налаштуємо його запуск від імені системного користувача syslog та групи adm.

Змінимо власника робочої директорії для файлу позицій:

sudo chown -R syslog:adm /var/lib/promtail

Тепер створимо юніт-файл для systemd: 

sudo tee /etc/systemd/system/promtail.service > /dev/null <<EOF

[Unit]

Description=Promtail Service

After=network.target

[Service]

User=syslog

Group=adm

ExecStart=/usr/local/bin/promtail -config.file=/etc/promtail/promtail-config.yaml

Restart=on-failure

RestartSec=5

[Install]

WantedBy=multi-user.target

EOF

4. Запуск агента

Активуємо та запускаємо службу Promtail:

sudo systemctl daemon-reload

sudo systemctl enable promtail

sudo systemctl start promtail

Перевіряємо статус роботи:

sudo systemctl status promtail

Якщо статус зелений, значить, агент успішно просканував вказані директорії, зафіксував поточні позиції у файлі positions.yaml і почав відправляти перші пакети логів у Loki.

Крок 5. Інтеграція з Grafana та робота з LogQL

Всі дані вже успішно збираються в Loki. Залишилося підключити це сховище до нашої візуальної панелі Grafana та навчитися робити базові пошукові запити.

1. Підключення джерела даних (Data Source)

1. У лівому бічному меню Grafana перейдіть у розділ Connections (значок шестерні або компаса) -> Data sources.
2. Натисніть синю кнопку Add data source.
3. У пошуковому рядку введіть Loki та клікніть на інструмент, що з’явився у списку.
4. У вікні налаштувань знайдіть поле HTTP -> URL. Оскільки Loki працює на тому самому сервері, введіть: http://localhost:3100
5. Прокрутіть сторінку до самого низу та натисніть Save & test.

Якщо все налаштовано правильно, Grafana виконає тестовий запит до API сховища і видасть зелене повідомлення: «Data source successfully connected».

2. Візуалізація та аналіз даних через Explore

Для швидкого аналізу та пошуку логів без створення постійних графіків у Grafana є чудовий інструмент — Explore.

1. У лівому меню перейдіть у розділ Explore (значок із компасом або відповідний пункт меню).
2. У верхньому спадному списку переконайтеся, що як джерело даних обрано саме Loki.
3. Для написання запитів тут використовується спеціальна мова LogQL. Вона дуже схожа на синтаксис Prometheus (PromQL) і є неймовірно гнучкою.

Спробуймо зробити перший запит через поле тексту запиту (Query):

{job="varlogs"} 

Натисніть кнопку Run query у правому верхньому кутку. Нижче з’явиться стрічка текстових логів, які Promtail зчитує з папки /var/log//*.log.

Якщо ви хочете відстежити роботу конкретного системного демона (наприклад, служби SSH або файрволу), який ми збираємо через systemd-journal, запит виглядатиме так:

{job="systemd-journal", unit="ssh.service"} 

3. Створення постійного дашборду

Щоб не писати запити щоразу вручну, виведемо логи на постійну панель моніторингу:

1. Перейдіть у розділ Dashboards -> New -> Add Visualization.
2. Оберіть Loki як джерело даних.
3. У полі запиту введіть потрібний фільтр (наприклад, {job="varlogs"}).
4. У правій панелі налаштувань знайдіть блок Visualization і замість стандартного Time series (графіка) оберіть тип Logs.
5. У верхньому правому кутку увімкніть режим Live. Тепер нові рядки логів будуть з’являтися на екрані автоматично, щойно вони запишуться на сервері.
6. Натисніть Save та збережіть дашборд під назвою «System OS Logs».

Післяслово

Базове налаштування логів за гайдами — це хороший старт, але в реальному production-середовищі інженеру потрібно вміти будувати комплексні системи збору метрик, налаштовувати алертинг про збої в Telegram або Slack та моніторити складні мережеві протоколи.

Якщо ви хочете вийти на професійний рівень та керувати стабільністю великих IT-інфраструктур, переходьте на курс «Системи моніторингу на Linux» від ITEDU. На курсі ви детально розберете не лише роботу з логами, а й розгортання Prometheus, Zabbix, побудову складних дашбордів у Grafana та автоматизацію моніторингу реальних серверів.