<- До підрозділу

Telegraf: теоретична частина

1. Загальні поняття

Telegraf — це агент збору метрик з відкритим вихідним кодом, розроблений компанією InfluxData. Його основна функція — отримання, обробка та передача даних у системи зберігання, такі як InfluxDB, Prometheus, MQTT-брокери або інші сервіси. Завдяки модульній архітектурі з більш ніж 300 плагінами, Telegraf може збирати дані з широкого спектра джерел: системні метрики, журнали, датчики, мережеві пристрої (через SNMP), MQTT, OPC UA, Modbus, SQL-бази, http-endpoints тощо. Агент підтримує як перетворення даних, так і агрегацію, фільтрацію та мультиканальну відправку, що робить його ключовим компонентом у побудові інфраструктури моніторингу та IIoT-рішень.

Що саме повинен робити агент Telegraf задається у конфігураційному файлі. У цьому файлі потрібно вказати, які плагіни будуть використовуватись. Кожен конфігураційний файл повинен містити принаймні один увімкнений вхідний плагін (звідки надходять метрики) і щонайменше один вихідний плагін (куди метрики надсилаються). При запуску Telegraf вказується який саме конфігураційний файл використовується.

Метрики

Метрики Telegraf — це внутрішнє представлення даних, яке використовується під час обробки. Вони тісно пов’язані з моделлю даних InfluxDB і складаються з чотирьох основних компонентів:

• Назва вимірювання (measurement name): опис і простір імен для метрики.
• Теги (tags): пари ключ/значення у вигляді рядків, зазвичай використовуються для ідентифікації метрики.
• Поля (fields): пари ключ/значення з типами даних, зазвичай містять значення самої метрики.
• Часова мітка (timestamp): дата й час, що відповідають полям.

Метрики Telegraf існують лише в оперативній пам’яті й повинні бути перетворені в конкретний формат для передачі або перегляду. Для цього Telegraf надає вихідні формати даних (також відомі як серіалізатори). Типовий серіалізатор Telegraf перетворює метрики у формат InfluxDB line protocol, що забезпечує високу продуктивність і пряме відображення кожної метрики Telegraf у формат InfluxDB.

Формат InfluxDB line protocol, який використовується Telegraf для виводу метрик у консоль (а також для передачі в базу даних або інші вихідні плагіни), має чітку структуру. Кожен рядок метрики складається з трьох частин: назви метрики (measurement), тегів (tags), полів (fields) та часової мітки (timestamp).

Загальний шаблон виглядає так:

<measurement>,<tag_key>=<tag_value>,... <field_key>=<field_value>,... <timestamp>

Де:

• Measurement - це логічна назва метрики або категорія, наприклад cpu, mem, disk, mqtt_consumer тощо. Вона визначає тип або джерело метрики.
• Tags (теги) - параметри, що описують контекст метрики. Вони завжди є рядками й використовуються для фільтрації та групування даних. Наприклад:

cpu=cpu0,host=raspberrypi,location=lab

• Fields (поля) - значення метрик. Кожне поле складається з пари ключ-значення. Поля можуть бути числовими, логічними або рядковими. Наприклад:

usage_user=12.3,usage_system=3.1,usage_idle=84.6

• Timestamp (часова мітка) - UNIX-час у наносекундах. Він показує момент часу, коли була зібрана метрика. Якщо він не вказаний явно, Telegraf вставляє поточну мітку автоматично при записі метрики.

Наприклад:

cpu,cpu=cpu0,host=osboxes usage_user=2.3,usage_system=1.1,usage_idle=96.6 1754638931000000000

Це означає, що:

• Зібрана метрика cpu
• Вона стосується ядра cpu0 на хості osboxes
• У момент часу, заданий міткою 1754638931000000000:
  • 2.3% процесора використовувалось користувацькими процесами
  • 1.1% — системними
  • 96.6% — перебувало в режимі очікування

Вивід у цьому форматі може бути надісланий до InfluxDB, збережений у файл або переданий через MQTT, у залежності від налаштованого вихідного плагіна та серіалізатора (data_format). Telegraf підтримує й інші серіалізатори, такі як json, graphite, wavefront, prometheus, але саме influx (InfluxDB line protocol) є найбільш ефективним та використовується за замовчуванням у багатьох конфігураціях.

Етапи організації збору метрик за допомогою Telegraf

У цьому розділі розглядається типовий порядок дій під час впровадження збору метрик із використанням агента Telegraf. Послідовне виконання кроків забезпечує ефективне налаштування системи моніторингу, яка може збирати, обробляти та передавати дані у потрібному форматі.

1) Визначення мети збору метрик. Першим кроком є чітке розуміння, які саме метрики потрібно збирати (наприклад, навантаження на процесор, обсяг доступної памʼяті, трафік у мережі, дані з датчиків тощо). Також слід визначити джерела метрик (локальна система, сторонні пристрої, API) та формат або середовище, в яке ці метрики будуть передаватись (InfluxDB, MQTT, файл, хмарна система тощо). 2) Встановлення Telegraf. На вибраному пристрої встановлюється Telegraf, зазвичай через менеджер пакетів (apt, yum, brew) або завантаженням окремого бінарного файла. Можливе також використання Telegraf у вигляді Docker-контейнера. 3) Створення початкової конфігурації. Telegraf дозволяє згенерувати шаблон конфігураційного файлу з усіма плагінами або тільки з обраними:

telegraf config --input-filter cpu:mem:disk --output-filter influxdb_v2 > telegraf.conf

Після генерації конфігурація редагується вручну відповідно до вимог.

4) Налаштування секції agent. У секції [agent] задаються глобальні параметри агента: періодичність збору метрик, частота надсилання, лог-файл, режим налагодження тощо. Наприклад:

[agent]
  interval = "10s"
  flush_interval = "10s"

5) Налаштування вхідних плагінів. У секціях [[inputs.*]] описуються джерела метрик. Це можуть бути як системні показники (cpu, mem, disk), так і зовнішні потоки (MQTT, HTTP, Modbus):

[[inputs.cpu]]
  percpu = true
  totalcpu = true

6) Додавання обробників і агрегаторів. Якщо потрібно перетворювати, обмежувати або агрегувати метрики, використовуються плагіни processors і aggregators. Наприклад, для перейменування поля або усереднення даних:

[[processors.rename]]
  [[processors.rename.replace]]
    field = "used_percent"
    dest = "memory_used_percent"

7) Налаштування вихідних плагінів. У секціях [[outputs.*]] задається, куди відправляти метрики. Наприклад, до бази даних InfluxDB або брокера MQTT:

[[outputs.mqtt]]
  servers = ["tcp://broker.local:1883"]
  topic_prefix = "metrics"
  data_format = "json"

8) Тестування конфігурації. Для одноразової перевірки можна виконати команду:

telegraf --config ./telegraf.conf --test

Вивід метрик у консоль дозволяє переконатися, що дані збираються коректно і без помилок.

9) Запуск Telegraf. Після перевірки Telegraf запускається як фоновий сервіс через systemd або вручну:

sudo systemctl start telegraf

або

telegraf --config ./telegraf.conf

10) Перевірка роботи та логування. Для перегляду логів використовується:

journalctl -u telegraf -f

або

tail -f /var/log/telegraf/telegraf.log

Це дозволяє вчасно виявити помилки або попередження.

11) Візуалізація метрик. Зібрані метрики можуть бути передані у системи візуалізації, наприклад, Grafana або Node-RED Dashboard.

12) Підтримка і розширення. З часом система може масштабуватись: додаються нові входи, виходи, обробка даних, дублювання на кілька хостів, централізоване управління конфігураціями.

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

2. Файл конфігурації

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

Під час запуску Telegraf використовуй прапорець --config, щоб вказати розташування конфігураційного файлу:

• Ім’я файлу та шлях, наприклад: --config /etc/default/telegraf
• Віддалена URL-адреса, наприклад: --config "http://remote-URL-endpoint"

Використовуй прапорець --config-directory, щоб включити всі файли з розширенням .conf у вказаній директорії до конфігурації Telegraf.

На більшості систем типовими шляхами є:

• /etc/telegraf/telegraf.conf — основний конфігураційний файл
• /etc/telegraf/telegraf.d (на Windows — C:\Program Files\Telegraf\telegraf.d) — директорія з додатковими конфігураційними файлами

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

Структура файлу

Конфігураційний файл Telegraf (telegraf.conf) є текстовим файлом у форматі TOML, який означує, як агент Telegraf повинен збирати, обробляти та надсилати метрики. Він складається з кількох ключових секцій, кожна з яких відповідає за певний аспект роботи агента.

• [agent] - центральна секція, що задає глобальні параметри роботи агента:
• [global_tags]- глобальні теги, які автоматично додаються до всіх зібраних метрик. Глобальні теги задаються у форматі ключ="значення".

• [[inputs.*]] - вхідні плагіни, описують джерела, з яких збираються метрики. Кожен плагін може мати власні параметри, а також фільтри (namepass, tagpass тощо). Кожен плагін може мати власні параметри, а також фільтри (namepass, tagpass тощо).

• [[processors.*]] - процесори (необов’язково), обробляють або модифікують метрики перед передачею. Обробляють або модифікують метрики перед передачею. Наприклад, перейменування, обчислення похідних значень або фільтрація тегів.

• [[aggregators.*]] - агрегатори (необов’язково), виконують обчислення над метриками (середнє, максимум, сума тощо) за певний період часу. Застосовуються до потоків даних перед вихідними плагінами.

• [[outputs.*]] - вихідні плагіни, означують, куди саме Telegraf буде надсилати метрики.

Загальна структура (схема)

[agent]
# глобальні налаштування

[global_tags]
# глобальні теги

[[inputs.*]]
# вхідні плагіни

[[processors.*]]
# (опційно) обробка метрик

[[aggregators.*]]
# (опційно) агрегування метрик

[[outputs.*]]
# вихідні плагіни

Ця структура дозволяє гнучко налаштовувати поведінку Telegraf у будь-яких сценаріях, як від простого моніторингу ресурсів Raspberry Pi до складних IoT-архітектур з агрегуванням та передачею в хмарні сервіси.

Нижче наведений приклад конфігураційного файлу Telegraf, який:

• збирає метрики використання:
  • оперативної памʼяті (mem)
  • ЦПУ (cpu)
  • диску (disk)
• публікує їх у MQTT-брокер
• містить усі основні секції: [agent], [global_tags], [[inputs.*]], [[outputs.mqtt]]

# --------------------
# [1] Глобальні параметри агента
# --------------------
[agent]
  interval = "10s"             					# Інтервал збору метрик
  flush_interval = "10s"       					# Інтервал відправки метрик
  logfile = "/var/log/telegraf/telegraf.log"  	# Файл логів

# --------------------
# [2] Глобальні теги
# --------------------
[global_tags]
  location = "lab"
  device = "raspberrypi"

# --------------------
# [3] Вхідні плагіни (джерела метрик)
# --------------------

# CPU
[[inputs.cpu]]
  percpu = true
  totalcpu = true
  collect_cpu_time = false
  report_active = false

# Оперативна пам’ять
[[inputs.mem]]

# Диск
[[inputs.disk]]
  ignore_fs = ["tmpfs", "devtmpfs", "overlay"]

# --------------------
# [4] Обробка (не використовується у цьому прикладі)
# --------------------
# [[processors.*]]
# (опційно)

# --------------------
# [5] Агрегатори (не використовується у цьому прикладі)
# --------------------
# [[aggregators.*]]
# (опційно)

# --------------------
# [6] Вихідний плагін: MQTT
# --------------------
[[outputs.mqtt]]
  servers = ["tcp://localhost:1883"]
  topic_prefix = "telegraf/metrics"
  username = "mqtt_user"         # (за потреби)
  password = "mqtt_password"     # (за потреби)
  client_id = "telegraf-publisher"
  qos = 0
  retain = false
  data_format = "json"

У цьому приклад дані публікуються в топіки типу:

telegraf/metrics/cpu
telegraf/metrics/mem
telegraf/metrics/disk

Формат публікації: JSON (наприклад, для mem):

{
  "used_percent": 45.23,
  "total": 952107008,
  ...
}

Генерування файлу

Команда telegraf config дає змогу згенерувати конфігураційний файл на основі списку плагінів Telegraf. Щоб згенерувати конфігураційний файл із типовими вхідними та вихідними плагінами, введи в терміналі таку команду:

telegraf config > telegraf.conf

Згенерований файл містить параметри для всіх доступних плагінів — деякі з них увімкнено, інші закоментовано.

Щоб згенерувати конфігураційний файл лише з потрібними плагінами, використовуй параметри --input-filter і --output-filter для вказання вхідних і вихідних плагінів. Імена плагінів розділяються двокрапкою (:).

telegraf \
--input-filter <НАЗВА_ВХІДНОГО_ПЛАГІНА>[:<ІНШИЙ_ВХІДНИЙ_ПЛАГІН>] \
--output-filter <НАЗВА_ВИХІДНОГО_ПЛАГІНА>[:<ІНШИЙ_ВИХІДНИЙ_ПЛАГІН>] \
config > telegraf.conf

Наведена нижче команда включає конфігураційні секції лише для плагінів inputs.cpu, inputs.http_listener_v2, outputs.influxdb_v2 та outputs.file:

telegraf \
--input-filter cpu:http_listener_v2 \
--output-filter influxdb_v2:file \
config > telegraf.conf

Змінні середовища

У конфігураційному файлі можна використовувати змінні середовища, обгорнувши їх у ${}.

• Для рядків змінні потрібно вказувати в лапках, наприклад: "test_${STR_VAR}"
• Для чисел і логічних значень — без лапок, наприклад: ${INT_VAR}, ${BOOL_VAR}

Змінні середовища можна також задавати за допомогою команди export у Linux:

export password=mypassword

Примітка: для зберігання конфіденційних облікових даних слід використовувати сховище секретів або змінні середовища.

Наприклад:

USER="alice"
INFLUX_URL="https://cloud2.influxdata.com"
INFLUX_SKIP_DATABASE_CREATION="true"
INFLUX_PASSWORD="monkey123"

У конфігураційному файлі Telegraf (/etc/telegraf.conf) посилайся на ці змінні, наприклад:

[global_tags]
user = "${USER}"

[[inputs.mem]]

[[outputs.influxdb]]
  urls = ["${INFLUX_URL}"]
  skip_database_creation = ${INFLUX_SKIP_DATABASE_CREATION}
  password = "${INFLUX_PASSWORD}"

Коли Telegraf запуститься, кінцева конфігурація виглядатиме так:

[global_tags]
  user = "alice"

[[outputs.influxdb]]
  urls = "https://cloud2.influxdata.com"
  skip_database_creation = true
  password = "monkey123"

Конфігурація агента

Секція [agent] у конфігураційному файлі Telegraf визначає глобальні параметри роботи агента, які застосовуються до всіх плагінів. Вона задає, як часто збирати метрики, як їх буферизувати та коли відправляти на вихідні плагіни. Інші секції (inputs, outputs, processors, aggregators) вже працюють у межах цих глобальних параметрів.

Щоб правильно налаштувати параметри секції [agent] у Telegraf, варто розуміти, як саме працює процес збору та відправлення метрик. Агент Telegraf виконує періодичне опитування джерел метрик (через вхідні плагіни), обробляє ці метрики (за потреби), і надсилає їх далі (через вихідні плагіни) у бази даних, брокери або інші системи. Основні етапи:

1. Збір. З вхідних джерел (наприклад, CPU, пам’ять, диск, MQTT, Modbus тощо) кожні interval секунд. Тобто це робота з вхідними плагінами.
2. Буферизація. Метрики тимчасово зберігаються в оперативній памʼяті. Якщо відправлення неможливе (наприклад, мережа недоступна) - зберігаються до metric_buffer_limit.
3. Скидання (flush). Зібрані метрики надсилаються на вихід (InfluxDB, MQTT, файл тощо) кожні flush_interval секунд пакетами по metric_batch_size записів. Тобто це робота з вихідними плагінами.

Загалом, секція [agent] означує темп, ритм і навантаження агента, а також базову стратегію його роботи. Правильне налаштування цих параметрів важливе для стабільної та ефективної роботи всієї системи збору метрик. На цей процес впливають різноманітні параметри, зокрема:

Якщо метрики надходять занадто часто або створюють велике навантаження можна збільшити interval. Якщо система не встигає надсилати дані тоді можна збільшити flush_interval або metric_buffer_limit. Якщо багато пристроїв збирають дані одночасно, можна додати collection_jitter, щоб розподілити навантаження у часі.

Секція [agent] містить такі параметри конфігурації:

• interval: Типовий інтервал збору даних для всіх вхідних плагінів.
• round_interval: Округлює час збору до кратного interval. Наприклад, якщо interval = 10s, агент буде збирати дані о :00, :10, :20 тощо.
• metric_batch_size: Кількість метрик, що відправляються в одному пакеті (batch).
• metric_buffer_limit: Розмір буфера метрик для кожного вихідного плагіна. Буфер очищається після успішного запису. Має бути кратним metric_batch_size і не меншим за його подвоєне значення.
• collection_jitter: Випадкове зміщення (jitter) часу збору. Кожен плагін «спить» випадковий проміжок часу в межах jitter перед збором. Це допомагає уникнути одночасного доступу до, наприклад, sysfs, що може навантажувати систему.
• flush_interval: Типовий інтервал відправлення даних усіма вихідними плагінами. Не повинен бути меншим за interval. Максимальний інтервал — це flush_interval + flush_jitter.
• flush_jitter: Випадкове зміщення інтервалу відправки. Використовується для уникнення пікових навантажень при одночасному запуску кількох інстансів Telegraf. Наприклад, при flush_interval = 10s і flush_jitter = 5s відправка буде відбуватись кожні 10–15 секунд.
• precision: Округлення зібраних метрик до вказаної точності (інтервал у форматі: 1ns, 1us, 1ms, 1s). Не використовується для сервісних вхідних плагінів (наприклад, logparser, statsd).
• debug: Запуск Telegraf у режимі налагодження (debug).
• quiet: Запуск Telegraf у тихому режимі — лише помилки.
• logtarget: Куди виводити логи — "file", "stderr", або (для Windows) "eventlog". Якщо "file" — використовується параметр logfile.
• logfile: Ім’я файлу для логів, якщо logtarget = "file". Якщо значення порожнє — логи пишуться в stderr.
• logfile_rotation_interval: Обертання (ротація) лог-файлу після вказаного часу. Якщо 0 — ротація за часом не виконується.
• logfile_rotation_max_size: Ротація логів, коли розмір перевищує вказане значення. Якщо 0 — ротація за розміром не виконується.
• logfile_rotation_max_archives: Максимальна кількість збережених архівів логів. Старіші файли видаляються. Якщо -1 — архіви не видаляються.
• log_with_timezone: Тимчасова зона для запису в логах. Наприклад: "America/Chicago". Щоб використовувати локальний час, вкажи "local".
• hostname: Перевизначення імені хоста. Якщо порожнє — використовується os.Hostname().
• omit_hostname: Якщо true, тег host не додається до метрик.
• skip_processors_after_aggregators: Якщо true, процесори не запускаються повторно після агрегаторів. Типове значення — false.

Конфігурація вхідного плагіна

Вхідні плагіни Telegraf використовуються для збору метрик із системи, сервісів або сторонніх API. Усі метрики збираються через ті джерела, які увімкнуті і налаштовані у конфігураційному файлі Telegraf. Окрім форматів даних, специфічних для окремих плагінів, Telegraf підтримує набір загальних форматів, які доступні при налаштуванні багатьох вхідних плагінів.

Наступні параметри конфігурації доступні для всіх вхідних плагінів:

• alias: Ім’я конкретного екземпляра плагіна.
• interval: Як часто збирати цю метрику. Зазвичай усі плагіни використовують глобальний інтервал, але якщо потрібно, щоб певний плагін виконувався рідше або частіше, це можна вказати тут. Збільшення значення може допомогти зменшити навантаження.
• precision: Перевизначає параметр precision агента. Зібрані метрики округлюються до заданої точності у вигляді інтервалу. Якщо вказано для сервісного плагіна (наприклад, statsd), кілька подій із однаковим часом можуть бути об’єднані при записі у базу даних.
• collection_jitter: Перевизначає глобальне значення collection_jitter агента. Використовується для випадкового зміщення часу збору, щоб уникнути одночасного навантаження на систему.
• name_override: Перевизначає базову назву вимірювання (за замовчуванням — назва плагіна).
• name_prefix: Додає префікс до назви вимірювання.
• name_suffix: Додає суфікс до назви вимірювання.
• tags: Набір тегів, які застосовуються до метрик цього плагіна.

Конфігурація вихідного плагіна

• alias: Ім’я конкретного екземпляра плагіна.
• flush_interval: Максимальний інтервал між відправками даних. Дозволяє перевизначити глобальний параметр flush_interval агента для окремого плагіна.
• flush_jitter: Час випадкового зміщення інтервалу відправки. Перевизначає flush_jitter агента для конкретного плагіна.
• metric_batch_size: Максимальна кількість метрик, які надсилаються одночасно. Перевизначає параметр metric_batch_size агента.
• metric_buffer_limit: Максимальна кількість не надісланих метрик у буфері. Перевизначає metric_buffer_limit агента.
• name_override: Перевизначає базову назву вимірювання (за замовчуванням — назва вихідного плагіна).
• name_prefix: Додає префікс до назви вимірювання.
• name_suffix: Додає суфікс до назви вимірювання.

Конфігурація агрегатора

Наступні параметри конфігурації доступні для всіх агрегаторів:

• alias: Ім’я конкретного екземпляра плагіна.
• period: Період, з якою агрегатор скидає (flush) та очищає зібрані дані. Усі метрики з часовими мітками поза межами цього періоду ігноруються агрегатором.
• delay: Затримка перед тим, як агрегатор виконує відправку даних. Використовується для того, щоб агрегатори встигли зібрати метрики від вхідних плагінів, якщо збір і скидання мають однаковий інтервал.
• grace: Тривалість, протягом якої плагін агрегує метрики, навіть якщо вони надходять із запізненням (поза межами періоду). Цей параметр корисний у випадках, коли очікується запізніле надходження метрик, і дає змогу включити їх у наступний період агрегації.
• drop_original: Якщо встановлено true, агрегатор видаляє початкову метрику та не надсилає її у вихідні плагіни.
• name_override: Перевизначає базову назву вимірювання (за замовчуванням — назва вхідного плагіна).
• name_prefix: Додає префікс до назви вимірювання.
• name_suffix: Додає суфікс до назви вимірювання.
• tags: Набір тегів, які застосовуються до метрик від конкретного вхідного плагіна.

Конфігурація процесора

Наступні параметри конфігурації доступні для всіх процесорів:

• alias: Ім’я конкретного екземпляра плагіна.
• order: Порядок виконання процесорів. Якщо не вказано — порядок буде випадковим.

Параметри фільтрації метрик можна використовувати для обмеження обробки певних метрик процесором. Вилучені метрики передаються далі до наступного процесора.

Фільтрація метрик

Фільтри можна налаштовувати окремо для вхідних, вихідних, процесорів або агрегаторів. Фільтри:

• namepass: Масив шаблонів (glob patterns). Пропускаються лише метрики, назви яких відповідають хоча б одному з шаблонів.
• namedrop: Обернений до namepass. Відкидає метрики, назви яких відповідають шаблонам у цьому списку. Застосовується після namepass.
• fieldpass: Масив шаблонів для назв полів. Пропускаються лише ті поля, ключі яких відповідають шаблонам.
• fielddrop: Обернений до fieldpass. Відкидає поля з ключами, що відповідають шаблонам.
• tagpass: Таблиця, яка зіставляє ключі тегів з масивами шаблонів значень. Пропускаються лише ті метрики, що мають тег із відповідним ключем і значенням, що відповідає шаблону.
• tagdrop: Обернений до tagpass. Відкидає метрики, що мають тег із ключем і значенням, які відповідають шаблону. Застосовується після tagpass.
• taginclude: Масив шаблонів. Пропускаються лише теги, ключі яких відповідають шаблонам. На відміну від tagpass, цей фільтр видаляє всі теги, що не відповідають умовам, але не відкидає саму метрику. Ефективніше використовувати на вході.
• tagexclude: Обернений до taginclude. Видаляє теги, ключі яких відповідають шаблонам.

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

4. Команди та прапорці telegraf

Якщо просто виконати команду:

telegraf

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

• Файл конфігурації: Telegraf за замовчуванням шукає файл за шляхом:

  /etc/telegraf/telegraf.conf
  

  Якщо файл існує та валідний, то Telegraf запускається, виконує збір метрик відповідно до конфігурації, і публікує їх у вказане джерело (наприклад, InfluxDB або MQTT).

• Якщо файл не знайдено або містить помилки, то Telegraf завершить роботу з повідомленням про помилку (stderr).

Команда telegraf запускає всі необхідні процеси для роботи агента Telegraf. Синтаксис використання

telegraf [команди]
telegraf [прапорці]

Команди

Глобальні прапорці

Ці команди та прапорці дозволяють гнучко керувати роботою агента Telegraf — як для одноразового збору, так і для постійного моніторингу.

Нижче наведено кілька пркладів.

Створити повний конфігураційний файл:

telegraf config > telegraf.conf

Згенерувати конфігурацію лише з окремими плагінами:

telegraf config \
  --input-filter cpu \
  --output-filter influxdb

Запустити одну конфігурацію Telegraf і вивести метрики у stdout:

telegraf --config telegraf.conf --test

Запустити Telegraf з усіма плагінами, визначеними у конфігураційному файлі:

telegraf --config telegraf.conf

Запустити Telegraf, але увімкнути лише вибрані плагіни:

telegraf \
  --config telegraf.conf \
  --input-filter cpu:mem \
  --output-filter influxdb

Запустити Telegraf з увімкненим pprof (для профілювання):

telegraf \
  --config telegraf.conf \
  --pprof-addr localhost:6060

5. Огляд вхідних плагінів

Нижче подано класифікацію вхідних плагінів (input plugins) Telegraf — за категоріями, відповідно до джерел даних, з яких збираються метрики:

1) Системні метрики (System Metrics). Ці плагіни збирають інформацію безпосередньо з операційної системи, апаратного забезпечення або ядра.

• cpu — завантаження процесора
• mem — використання оперативної пам’яті
• disk — статистика дискових розділів
• diskio — дискові операції вводу/виводу
• swap — використання swap-пам’яті
• net, netstat — активність мережевих інтерфейсів
• processes — кількість і стан процесів
• kernel — загальні метрики ядра (контекстні перемикання тощо)
• system — аптайм, користувачі, хостнейм, час

2) Мережеві плагіни. Моніторинг стану мережі, доступності вузлів та якості з’єднання.

• ping — час відгуку і втрата пакетів (ICMP)
• http_response — час відгуку вебсервера
• net_response — доступність TCP/UDP портів
• dns_query — перевірка доступності DNS
• socket_listener — прослуховування сокетів для надходження метрик
• ipmi_sensor — апаратні сенсори через IPMI

3) Промислові та протокольні плагіни. Для підключення до промислових або спеціалізованих протоколів.

• modbus — зчитування даних з Modbus-пристроїв
• snmp — збір метрик через SNMP
• opcua — підтримка OPC UA
• s7 — підключення до Siemens PLC через S7-протокол
• mqtt_consumer — отримання метрик з MQTT-брокера

4) Системи моніторингу та логів. Отримання даних із систем логування, обліку або моніторингу.

• logparser — читання лог-файлів
• tail — спостереження за новими записами у логах
• eventlog — Windows Event Log
• win_perf_counters — продуктивність у Windows

5) Бази даних. Збір статистики з баз даних та моніторинг їхнього стану.

• mysql, postgresql, mssql, oracle, sqlite — підключення до відповідних СУБД
• influxdb — метрики з іншого сервера InfluxDB
• redis — інформація про Redis
• mongodb — моніторинг MongoDB
• elasticsearch — статус кластера, індекси

6) Контейнери та віртуалізація. Збір метрик із систем контейнеризації, кластеризації та віртуалізації.

• docker — статистика контейнерів Docker
• kubernetes — через kubelet API
• cgroup — Linux cgroups
• containerd, cri, rkt — альтернативи Docker

7) Обмін повідомленнями та брокери. Інтеграція з потоками даних або повідомлень.

• mqtt_consumer — споживання MQTT-повідомлень
• kafka_consumer — Kafka
• nats_consumer — NATS
• amqp_consumer — RabbitMQ

8) Хмарні сервіси. Отримання метрик із хмарних або зовнішніх API.

• cloudwatch, stackdriver, azure_monitor — метрики з AWS, Google Cloud, Azure
• http, http_listener — запити до зовнішніх HTTP-API або прослуховування HTTP-запитів

9) Файли, скрипти, утиліти. Отримання даних з файлів, команд чи скриптів.

• exec — запуск зовнішнього скрипта, отримання stdout як метрики
• execd — запуск довготривалого процесу
• file — читання даних із файлів
• csv, json, xml — парсинг даних у цих форматах
• starlark — написання кастомної логіки на Python-подібному DSL

10) Тестові та службові

• internal — збір внутрішніх метрик самого Telegraf
• dummy, random, sample — тестові плагіни для налагодження
• procstat — моніторинг окремих процесів

Якість мережі

Щоб збирати метрики якості мережі та моніторити зв’язок із пристроями, Telegraf має кілька плагінів, які можуть бути корисні залежно від типу перевірки:

• inputs.ping – найпростіший спосіб перевірки доступності. Пінгує один або кілька IP-адрес або доменів, щоб виміряти:

  • затримку (average_response_ms, percent_packet_loss, maximum_response_ms, minimum_response_ms)
  • доступність (чи відповідає взагалі, result_code)

  Працює у двох режимах:

  • method = "exec" – використовує системну утиліту ping (за замовчуванням).
  • method = "native" – надсилає ICMP напряму (без зовнішніх програм), потрібен CAP_NET_RAW або root.

  Приклад конфігурації:

  [[inputs.ping]]
    urls = ["192.168.1.1", "google.com"]
    count = 5
    method = "native"
    ping_interval = 1.0
    timeout = 2.0
    data_format = "influx"
  

• inputs.net_response – для перевірки TCP або UDP портів. Дозволяє перевірити, чи відкритий порт на віддаленому пристрої і скільки часу займає підключення. Добре підходить для моніторингу пристроїв з Modbus, веб-серверів, MQTT-брокерів тощо.

  Приклад конфігурації:

  [[inputs.net_response]]
    protocol = "tcp"
    address = "192.168.1.50:502"
    timeout = 1.0
  

• inputs.net – збирає базові метрики про мережеві інтерфейси локальної машини: обсяг трафіку, кількість помилок, дропів тощо.

• inputs.dns_query – перевірка якості роботи DNS. Дозволяє відстежувати доступність DNS-серверів і час відповіді на DNS-запити.

6. Огляд вихідних плагінів

Нижче наведена класифікація вихідних плагінів (output plugins) у Telegraf за основними напрямами використання. Це дозволяє краще зорієнтуватися у виборі плагіна залежно від того, куди саме мають передаватися зібрані метрики.

1) Бази даних часових рядів (Time Series Databases). Це найпоширеніше призначення вихідних плагінів — передача метрик до спеціалізованих СУБД для аналізу часових рядів.

• influxdb, influxdb_v2 — передача в InfluxDB (версії 1.x або 2.x)
• prometheus_client — відкриття HTTP-серверу для збирання метрик Prometheus
• graphite — для надсилання у Graphite
• opentsdb — підтримка OpenTSDB через Telnet API
• kairosdb — для бази KairosDB
• timescaledb — передача до TimescaleDB (через SQL)

2) Бази даних загального призначення. Передача метрик у класичні реляційні або NoSQL СУБД для збереження, звітності або подальшої обробки.

• postgresql — запис у PostgreSQL
• sql — запис у будь-яку SQL-базу через конфігурований драйвер
• mongodb — запис у MongoDB
• clickhouse — підтримка ClickHouse
• sqlite — запис у SQLite-файл
• oracle — для баз Oracle (через OCI)
• dynamodb — передача в Amazon DynamoDB

3) Повідомлення та брокери повідомлень (Message Brokers / Queues). Для інтеграції з системами обміну повідомленнями в реальному часі або підключення до інших систем через брокери.

• mqtt — передача у MQTT-брокер
• amqp — через Advanced Message Queuing Protocol (RabbitMQ)
• kafka — публікація в Kafka (Apache Kafka)
• nats — для надсилання через NATS
• nsq — інтеграція з NSQ
• redis — підтримка публікації через Redis pub/sub
• pubsub — Google Cloud Pub/Sub
• azure_monitor — інтеграція з Azure

4) Файлові системи та логи. Для локального збереження метрик у файлах або журналізації.

• file — запис у файл у заданому форматі (наприклад, JSON, line protocol)
• csv — у CSV-файл
• json_file — збереження метрик у JSON-файл
• cloudwatch_logs — відправлення до AWS CloudWatch Logs
• elasticsearch — запис у Elasticsearch
• logzio — інтеграція з Logz.io

5) Системи моніторингу та візуалізації. Надсилання метрик у зовнішні системи для моніторингу або побудови графіків.

• datadog — передача метрик у Datadog
• wavefront — для VMware Wavefront
• newrelic — надсилання у New Relic
• librato — підтримка Librato
• signalfx — інтеграція з SignalFx (Splunk)
• stackdriver — для Google Cloud Monitoring
• splunkmetric — передача до Splunk

6) Хмарні сервіси та API. Вихідні плагіни для взаємодії з хмарними або вебсервісами.

• http — надсилання метрик через HTTP POST у кастомне API
• azure_monitor, cloudwatch, google_cloud_monitoring — для хмарних моніторингових сервісів
• sapm, otlp — для підтримки OpenTelemetry/Trace

7) Інше. Інші нестандартні методи або спеціалізовані протоколи передачі.

• socket_writer — надсилання через TCP/UDP сокет
• wavefront, riemann — підтримка відповідних сервісів
• sqlstore, procstat (небезпосередньо не вихідні, але можуть комбінуватися)

Вибір плагіна залежить від системи, яка прийматиме метрики:

• Якщо використовується InfluxDB — influxdb або influxdb_v2
• Для MQTT — mqtt
• Для Prometheus — prometheus_client
• Для збереження у файл — file або csv
• Для інтеграції з хмарою — обрати відповідний плагін (cloudwatch, azure_monitor, stackdriver)

7. Процесори

8. Агрегатори

9. Формати

https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md

1. InfluxDB Line Protocol
2. Binary
3. Carbon2
4. CloudEvents
5. CSV
6. Graphite
7. JSON
8. MessagePack
9. Prometheus
10. Prometheus Remote Write
11. ServiceNow Metrics
12. SplunkMetric
13. Template
14. Wavefront

Теоретичне заняття розробив Прізвище або нік розробника Імя.