В этой статье мы настроим отправку телеметрии с контроллера Wiren Board в observability-платформу Яндекс Monium с помощью агента Telegraf.
Зачем это нужно? Умный дом — это не только удобство, но и сложная система, состоящая из множества устройств, протоколов связи. Чтобы всё работало, важно наблюдать за состоянием и своевременно получать оповещения о проблемах.
Независимая платформа-наблюдатель останется онлайн и сможет оповестить о проблеме, даже если дома пропадёт электричество или нарушится связь.
Язык запросов SEL позволяет перейти от простого наблюдения к настоящей аналитике: вы можете находить аномалии, сопоставлять события во времени и даже строить прогнозы — например, предсказывать перегрев по тренду роста температуры.
Здесь мы не станем сравнивать Monium с другими системами мониторинга — ни по функциональности, ни по архитектуре. Вместо этого сфокусируемся на одном: как шаг за шагом подключить Wiren Board к платформе и начать отправлять телеметрию.
А вы, дорогие читатели, расскажите в комментариях — какие решения используете и в чём заключаются их сильные стороны. Возможно, ваш опыт поможет другим выбрать подходящий путь.
Подготовка Яндекс Cloud
Для начала понадобится выполнить вход через Яндекс ID, создав свою первую организацию и облако.
ℹ️ Примечание: слово «организация» здесь — не юридическое понятие вроде ИП или ООО, а инструмент управления ресурсами. Это корневой контейнер: внутри вы создаёте облака, каталоги, настраиваете доступ и платёжные аккаунты.
Организацию может создать любой — физическое лицо, интегратор, компания.
Подробнее об иерархии ресурсов можно прочесть в официальной документации к Yandex Resource Manager.
На странице биллинга создайте платёжный аккаунт. С него будут расходоваться средства за потреблённый объём услуг. Подробнее про создание платёжного аккаунта можно узнать в руководстве.
После привязки платёжного аккаунта к облаку оно станет доступно для работы с Monium.
Вернёмся в консоль управления. Обратите внимание на каталог, созданный по умолчанию. Его идентификатор понадобится нам для настройки подключения с контроллера.
Следующим шагом создайте сервисный аккаунт и API-ключ. Обратите внимание, что сервисному аккаунту нужно выдать роль monium.telemetry.writer, а ключу указать область действия yc.monium.telemetry.write.
Срок действия ключа можно не задавать. Сформированный секретный ключ сохраните, чтобы указать его при подключении с контроллера в переменной окружения MONIUM_API_KEY.
Если вы пропустили назначение роли сервисному аккаунту, можно сделать это через меню каталога в консоли управления:
Проект Monium будет создан автоматически, как только на идентификатор каталога начнёт поступать телеметрия.
Установка Telegraf на контроллер
Перед установкой Telegraf понадобится установить gpg:
sudo apt update && sudo apt install gpg
Если этого не сделать, команда проверки ключа завершится ошибкой без уведомления о проблеме.
Далее скачайте ключ подписи и внесите его в систему доверенных ключей:
wget -q https://repos.influxdata.com/influxdata-archive.key
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 | grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' && cat influxdata-archive.key | gpg --dearmor | sudo tee /usr/share/keyrings/influxdata-archive.gpg > /dev/null
Обратите внимание, ключ нужно записать не в /etc/apt/trusted.gpg.d/, а в /usr/share/keyrings/ - так безопаснее.
Добавьте в список репозиториев ссылку на репозиторий Telegraf:
echo 'deb [signed-by=/usr/share/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian bullseye stable' | sudo tee /etc/apt/sources.list.d/influxdata.list
Обновите список пакетов и установите Telegraf:
sudo apt update && sudo apt install telegraf
Настройка Telegraf
Файл конфигурации
Основная конфигурация Telegraf находится в файле /etc/telegraf/telegraf.conf - этот файл очень подробный, содержит множество шаблонов. По умолчанию в нём уже активированы входы (inputs) для сбора системных метрик: загрузка CPU, использование оперативной памяти, состояние дисковой подсистемы и информация о запущенных процессах.
Обратите внимание на синтаксис TOML: секции, обрамлённые двойными квадратными скобками, такие как [[inputs.cpu]], обозначают отдельные экземпляры одного плагина. Например, вы можете создать несколько секций [[inputs.mqtt_consumer]], чтобы подключаться к разным брокерам.
Поскольку мы будем часто вносить изменения, удобнее не редактировать основной конфигурационный файл, а создать отдельный - специально для интеграции с Monium:
sudo nano /etc/telegraf/telegraf.d/monium.conf
Telegraf автоматически загружает все файлы из директории telegraf.d, поэтому новая конфигурация будет применена при перезапуске сервиса.
Настройка входа MQTT для сбора метрик
Добавьте в файл monium.conf следующую секцию (внутри секции используйте отступ из двух пробелов):
[[inputs.mqtt_consumer]]
servers = ["tcp://127.0.0.1:1883"]
client_id = "monium-controller-agent"
topics = [
"/devices/power_status/controls/Vin",
"/devices/wb-msw-v4_66/controls/Temperature",
"/devices/wb-msw-v4_66/controls/Sound Level",
]
data_format = "value"
data_type = "float"
Пояснение параметров:
- servers - указывает адрес брокера MQTT. В данном случае используется локальный экземпляр Mosquitto, работающий на контроллере Wiren Board. Аутентификация не требуется.
- client_id - уникальный идентификатор клиента MQTT для логов. По умолчанию Telegraf генерирует его автоматически, однако постоянно меняет. Фиксированное значение упростит диагностику.
- topics - список топиков, из которых будут собираться данные. Важно передавать в платформу только те метрики, которые необходимы для мониторинга состояния системы. Например, температуру, напряжение, состояние аварийных реле.
- data_format и data_type - задают формат и тип данных соответственно. В указанных ранее метриках содержатся простые значения дробных чисел.
ℹ️ Примечание: избегайте сбора избыточных данных с помощью wildcard-записей, таких как /devices/#. Monium - это не архив, а инструмент observability и каждое записанное значение тарифицируется. Отправка лишних метрик приведёт к неоправданному росту объёма данных и увеличению затрат.
Для целей данной статьи в качестве примера обрабатываются следующие топики:
- напряжение питания контроллера:
/devices/power_status/controls/Vin - температура и уровень шума, полученные одним из мультидатчиков WB-MSW v4 с Modbus-адресом 66:
/devices/wb-msw-v4_66/controls/Temperature
/devices/wb-msw-v4_66/controls/Sound Level
Проверка конфигурации: отладка и просмотр данных
Прежде чем наладить отправку метрик в Яндекс Monium, убедимся что Telegraf корректно собирает и структурирует данные. Для этого временно настроим вывод результата в консоль:
[[outputs.file]]
files = ["stdout"]
Telegraf считывает переменные окружения из файла /etc/default/telegraf. В дальнейшем мы разместим в нём ключ доступа к API Яндекса и идентификатор каталога для Monium.
Для удобной диагностики и отладки конфигурации вы можете вручную запустить Telegraf с учётом этих переменных, используя следующую команду:
env $(cat /etc/default/telegraf | grep -v '^#' | xargs) telegraf --debug
Как устроена эта команда:
- cat /etc/default/telegraf - читает содержимое файла с переменными окружения
- grep -v '^#' - исключает строки-комментарии (начинающиеся с #)
- xargs - преобразует строки в список аргументов вида key=value
- env $(...) - запускает команду telegraf в окружении, сформированном из этих переменных
- --debug - включает подробный режим вывода: вы увидите все этапы инициализации, сбора метрик и возможные ошибки.
Тестовый запуск позволит оценить корректность подключения к брокеру и проверить, как формируются метрики. Рекомендуется выполнять в отдельном терминале, чтобы не прерывать основную рабочую сессию.
Для остановки процесса нажмите Ctrl + C — это корректно завершит работу Telegraf и вернёт вас в командную строку.
Дополнительные теги и парсер топиков
По умолчанию плагин mqtt_consumer добавляет в метрики тег topic, содержащий полный путь MQTT-сообщения. Чтобы сделать данные более информативными, воспользуемся встроенным механизмом парсинга топиков, который позволяет извлекать фрагменты пути и формировать из них осмысленные метки.
Wiren Board следует особому соглашению об именовании топиков:
/devices/<deviceName>/controls/<controlName>
Чтобы извлечь названия устройств (power_status, wb-msw-v4_66) и контролов (Temperature, Sound Level, Vin), добавьте в конфигурацию mqtt_consumer секцию парсинга:
[[inputs.mqtt_consumer.topic_parsing]]
topic = "/devices/+/controls/+"
measurement = "/_/_/_/measurement"
tags = "/_/device/_/_"
Пояснение параметров:
- topic - шаблон, определяющий, какие топики обрабатываются данным парсером. Символ + означает «любое значение на этой позиции».
- measurement - указывает, какую часть топика использовать в качестве имени метрики.
Запись "/_/_/_/measurement" пропускает первые три сегмента, извлекая название контрола (<controlName>). В результате вместо mqtt_consumer вы получите метрики вроде Temperature, Vin и т.д. - tags - определяет, какие части топика превратятся в дополнительные теги.
Запись "/_/device/_/_" означает: второй сегмент (<deviceName>) будет добавлен как тег с ключом device.
Теперь тег topic дублирует извлечённую информацию - его можно исключить из выходных данных. Сразу после параметра data_type добавьте ещё один:
tagexclude = ["topic"]
В результате настройки вместо
mqtt_consumer,topic=/devices/wb-msw-v4_66/controls/Temperature value=26.1
вы получите
Temperature, device=wb-msw-v4_66 value=26.1
что значительно удобнее для запросов, фильтрации и визуализации в Яндекс Monium.
Нормализация метрик с помощью процессоров
Чтобы обеспечить единообразие именования метрик в Яндекс Monium, рекомендуется нормализовать их на этапе сбора.
Некоторые имена контролов в Wiren Board могут начинаться с заглавной буквы или содержать пробелы (например, Temperature, Sound Level). Это может затруднять работу с данными.
В контексте Monium, где используются языки запросов вроде SEL и PromQL, предпочтительны идентификаторы в нижнем регистре, с подчёркиванием вместо пробелов (snake_case). Такие имена проще использовать в запросах, алертах и дашбордах, также они соответствуют общепринятым best practices мониторинга.
Telegraf позволяет автоматически преобразовывать имена метрик с помощью процессоров. Добавьте следующие правила в файл monium.conf:
[[processors.strings]]
# Приведение к нижнему регистру
[[processors.strings.lowercase]]
measurement = "*"
# Замена пробелов на подчёркивания
[[processors.strings.replace]]
measurement = "*"
old = " "
new = "_"
После этого Temperature станет temperature, а Vin — vin. Также Sound Level превратится в sound_level.
ℹ️ Примечание: эти преобразования применяются ко всем входящим метрикам (measurement = "*"). При необходимости вы можете ограничить их конкретными тегами или условиями.
Настройка агрегаций для оптимизации телеметрии
Некоторые показатели (вроде уровня шума у датчика WB-MSW v4) меняются с высокой частотой, по нескольку раз в секунду. При мониторинге в observability-платформе такая детализация зачастую избыточна, особенно если цель - отслеживание общего состояния среды, а не анализ микрособытий.
Добавьте в файл monium.conf следующую секцию:
[[aggregators.basicstats]]
namepass = ["sound_level", "temperature"]
period = "1m"
drop_original = true
stats = ["count","min","max","mean","stdev", "s2"]
Пояснение параметров:
- namepass — список метрик, к которым применяется агрегация. Только указанные measurement будут обрабатываться
- period — интервал накопления данных. По истечении периода генерируется одна агрегированная запись
- drop_original — если true, исходные значения не передаются дальше по конвейеру. Это предотвращает дублирование данных
- stats — набор вычисляемых статистик: mean - среднее значение (основной показатель), min и max - минимальное и максимальное значения, count - число записей за период, stdev - стандартное отклонение, s2 - дисперсия.
К примеру, sound_level обновляется очень часто, отдавая по нескольку значений в секунду. Используя агрегацию, вы получите одну запись в минуту с полной статистикой:
sound_level,device=wb-msw-v4_66,host=your-host value_min=38.16,value_max=39.81,value_mean=38.85934579439252,value_s2=0.08461741038129124,value_stdev=0.2908907189672631,value_count=214 1774016760000000000
Это позволяет:
- сохранить информативность (вы видите не только среднее, но и разброс)
- снизить объём телеметрии в 60 и более раз
- существенно сократить количество операций записи в Monium, что напрямую снижает затраты.
ℹ️ Совет: используйте агрегацию для быстроизменяющихся метрик, не требующих миллисекундной точности. Для критичных событий (например, аварийные срабатывания) агрегацию лучше не применять.
Округление числовых значений
Агрегированные метрики, такие как среднее (mean) или стандартное отклонение (stdev), часто содержат избыточное количество знаков после запятой. Например, value_mean=38.85934579439252.
Такая точность не требуется ни для визуализации, ни для алертинга. Температура с точностью до 0.001°C или уровень шума с девятью знаками — это перебор.
Чтобы упростить данные и снизить объём передаваемой информации, воспользуемся процессором округления:
[[processors.round]]
namepass = ["sound_level", "temperature"]
precision = 2
Пояснение параметров:
- namepass — применяет процессор только к указанным метрикам;
- precision = 2 — округляет все числовые поля (value_mean, value_stdev и т.д.) до двух знаков после запятой.
Настройка отправки в Яндекс Monium
После обработки данных с помощью процессоров и агрегаторов настало время отправить метрики в Яндекс Monium. Для этого используется стандарт OpenTelemetry, реализованный в Telegraf через плагин [[outputs.opentelemetry]].
Добавьте в файл monium.conf следующую секцию:
[[outputs.opentelemetry]]
service_address = "ingest.monium.yandex.cloud:443"
encoding_type = "protobuf"
timeout = "5s"
insecure_skip_verify = true
compression = "gzip"
[outputs.opentelemetry.headers]
Authorization = "Api-Key ${MONIUM_API_KEY}"
x-monium-project = "${MONIUM_PROJECT}"
x-monium-cluster = "home"
x-monium-service = "controller"
Пояснение параметров:
- service_address — адрес приёмного шлюза Monium. Используется gRPC-эндпоинт по умолчанию.
- encoding_type = "protobuf" — формат сериализации данных.
- timeout = "5s" — максимальное время ожидания ответа от сервера.
- insecure_skip_verify = true — отключает проверку TLS-сертификата.
- compression = "gzip" — включает сжатие телеметрии перед отправкой, что снижает объём передаваемых данных и ускоряет доставку.
Заголовки аутентификации и контекста:
- Authorization — ваш API-ключ для доступа к Monium. Должен начинаться с префикса Api-Key
- x-monium-project — идентификатор проекта. Для каталога в облаке имеет вид folder__<ID>
- x-monium-cluster — логический кластер или зона (например, home или office). Полезно при масштабировании
- x-monium-service — имя сервиса или агента. В данном случае — controller, так как данные поступают с контроллера Wiren Board.
Не забудьте закомментировать секцию вывода данных в консоль [[outputs.file]], поставив в начале каждой строки символ решётки:
# [[outputs.file]]
# files = ["stdout"]
Перейдём в консоль контроллера и откроем файл с переменными окружения Telegraf на редактирование:
sudo nano /etc/default/telegraf
Значения нужно вводить без пробелов:
MONIUM_API_KEY=ваш_ключ_api
MONIUM_PROJECT=folder__идентификатор_каталога
При запуске Telegraf значения этих переменных окружения будут учтены в конфигурации. Держите свои идентификаторы в секрете и никому не показывайте.
Запуск Telegraf в боевом режиме выполняется командой
sudo systemctl start telegraf
Проверьте логи контроллера и убедитесь, что телеметрия корректно передаётся в облако.
Через некоторое время после запуска можно будет перейти на страницу своего проекта Monium, настроить метрики, алерты и дашборды.