Yandex Cloud
  • Сервисы
  • Решения
  • Почему Yandex Cloud
  • Сообщество
  • Тарифы
  • Документация
  • Связаться с нами
Подключиться
Language / Region
© 2022 ООО «Яндекс.Облако»
Yandex Monitoring
  • Начало работы
  • Пошаговые инструкции
    • Все инструкции
    • Работа с метриками
      • Поставка системных метрик Linux
      • Поставка метрик пользовательских приложений
      • Поставка метрик HAProxy и других сторонних приложений
      • Поставка метрик с хостов вне Yandex Cloud
      • Запись пользовательских метрик через API
      • Получение списка метрик
      • Выгрузка метрик
      • Экспорт метрик в формате Prometheus
    • Работа с дашбордами
      • Создание дашборда
      • Копирование дашборда
      • Добавление виджета на дашборд
      • Удаление виджета с дашборда
      • Удаление дашборда
    • Работа с алертами
      • Создание алерта
      • Создание канала уведомлений
      • Удаление алерта
  • Концепции
    • Обзор сервиса
    • Модель данных
    • Визуализация
      • Обзор
      • Строка запроса
      • Виджеты
      • Дашборд
    • Передача метрик
      • Агент для поставки метрик
        • Обзор
        • Установка и запуск
        • Конфигурирование
        • Рекомендации по использованию агента
    • Язык запросов
    • Алертинг
    • Прореживание данных
    • Удаление устаревших метрик (TTL)
    • Квоты и лимиты
  • Управление доступом
  • Правила тарификации
    • Действующие правила
    • Архив
      • Правила до 1 октября 2020 года
  • Справочник API
    • Аутентификация в API
    • REST
      • Обзор
      • MetricsData
        • Обзор
        • read
        • write
        • prometheusMetrics
      • MetricsMeta
        • Обзор
        • listLabelKeys
        • listLabelValues
        • listMetricNames
        • listMetrics
  • Справочник метрик
  • Вопросы и ответы
    • Общие вопросы
    • Навигация
    • Сбор и экспорт метрик
    • Метрики и единицы измерения
    • Алерты / уведомления
    • Все вопросы на одной странице
  1. Концепции
  2. Передача метрик
  3. Агент для поставки метрик
  4. Конфигурирование

Конфигурирование

Статья создана
Yandex.Cloud
  • Файлы конфигурации
  • Импорт конфигурационных файлов
  • Вывод и валидация итоговой конфигурации
  • Директивы конфигурации
    • Секция status
    • Секция storages
    • Секция routes
    • Секция channels
    • Секция pipes
    • Секция main_thread_pool
    • Секция agent_log
    • Секция system
    • Секция flow_control
    • Входы
    • Фильтры
    • Хранилища
    • Выходы
  • Примеры

Данный раздел описывает настройку Yandex Unified Agent. Перед настройкой рекомендуется ознакомиться с основными понятиями, которые используются в конфигурации агента.

Файлы конфигурации

Unified Agent конфигурируется YAML-файлами со следующими секциями:

  • routes — описание маршрутов доставок;
  • channels — описание именованных каналов;
  • pipes — описание именованных преобразований;
  • storages — описание хранилищ;
  • main_thread_pool — настройки системного пула потоков.

Также конфигурационный файл может содержать директиву import для импорта других файлов конфигурации.

Чтобы использовать файл конфигурации, передайте путь к нему в параметр командной строки --config при запуске агента. Например:

/usr/bin/unified_agent --config /etc/yandex/unified_agent/config.yml

При использовании Unified Agent, поставляемого в виде deb-пакета, базовый файл конфигурации /etc/yandex/unified_agent/config.yml автоматически устанавливается и передается в параметр --config.

Пользовательскую конфигурацию рекомендуется добавлять в отдельный файл в директории /etc/yandex/unified_agent/conf.d. Файлы из этой директории импортируются из базового файла конфигурации с помощью директивы import в алфавитном порядке. Механизм импорта описан в секции Импорт конфигурационных файлов данного раздела.

В разделе Примеры приведены различные примеры конфигураций, а также пример-справочник, содержащий полный список параметров конфигурации и их описание.

Импорт конфигурационных файлов

При помощи директивы import можно импортировать другие конфигурационные файлы. Значение директивы — строка или массив строк, каждая строка раскрывается при помощи функции glob. Файлы импортируются в порядке следования директив import, а внутри одной директивы — в лексикографическом порядке по именам файлов.

При импорте файлов конфигурации работают правила:

  • Разделы status и main_thread_pool будут взяты из последнего импортируемого файла.
  • Pазделы channels, storages, pipes и services представлены списком. Новые элементы дописываются в конец этого списка, либо заменяются, если совпадает name элемента.
  • Раздел routes представлен списком. Новые элементы дописываются в конец этого списка.

Директива import может содержаться в импортируемых файлах. Для этого в import укажите только абсолютные пути. Относительные пути отсчитываются от рабочей директории запуска агента.

Примечание

Не рекомендуем использовать import во вложенных файлах в целях упрощения конфигурации.

При циклическом импорте конфигурации Unified Agent завершится с ошибкой. Детали ошибки можно посмотреть в логах агента. Максимальная глубина рекурсии — 100. При ошибках в импортированном файле выводится полный путь к исходному импортированному файлу, содержащему ошибочный узел.

Вывод и валидация итоговой конфигурации

Чтобы провалидировать настройки агента, выполните команду:

unified_agent --config /etc/yandex/unified_agent/config.yml check-config

Если валидация успешна, агент выведет в stdout итоговый вариант после выполнения всех импортов и вернет нулевой код возврата.

Если валидация неуспешна, агент выведет ошибки конфигурации в stderr и вернет ненулевой код возврата:

$ unified_agent --config console_to_lb.yml check-config
yaml-cpp: error at line 10, column 3: unrecognized field [statos_port]

Директивы конфигурации

Ниже описаны секции конфигурации и параметры различных компонентов Unified Agent. Для необязательных параметров значения, приведенные в примерах, являются значениями по умолчанию.

Секция status

Секция содержит конфигурацию просмотра статуса Unified Agent.

status:  # необязательно
  # Просмотр статуса можно выключить при помощи значения false.
  enabled: true  # необязательный, по умолчанию true

  # Хост для просмотра статуса, null/пустая строка/:: — на всех интерфейсах.
  # По умолчанию, из соображений безопасности, сервис статуса доступен только локально.
  host: localhost  # необязательный

  # Порт для просмотра статуса.
  port: 16301  # обязательный

Секция storages

Секция содержит список хранилищ.

Описание хранилища состоит из следующих элементов:

  • name — имя хранилища, по которому на него можно сослаться из цепочки обработки;
  • plugin — плагин хранилища;
  • config — конфигурация входа. Параметры конфигурации всех хранилищ перечислены в разделе Хранилища.

Сослаться на хранилище из цепочки обработки можно при помощи директивы storage_ref.

Директива storage_ref состоит из следующих элементов:

  • name — имя хранилища, определенное в секции storages;
  • flow_control — настройки механизма создания сессий;

Пример секции storages:

storages:
- name: main
  plugin: fs
  config:
    directory: ./data/storage/main
    max_partition_size: 500mb
- name: secondary
  plugin: fs
  config:
    directory: ./data/storage/secondary
    max_partition_size: 100mb

Пример цепочки обработки, использующей хранилище:

pipe:
  - storage_ref:
      # Имя хранилища.
      name: main  # обязательный

      # Конфигурация инфраструктуры работы с сессиями.
      flow_control:
        new_sessions_rate_limit: null  # необязательный, по умолчанию не задан

Секция routes

Секция содержит список маршрутов доставки.

Маршрут доставки состоит из следующих элементов:

  • input — вход;
  • channel — канал.

Вход состоит из следующих элементов:

  • plugin — плагин входа;
  • config — конфигурация входа.
  • flow_control — конфигурация механизма создания сессий входа.

Канал состоит из следующих элементов:

  • pipe — цепочка обработки;
  • один из элементов:
    • output — содержит конфигурацию выхода;
    • channel_ref — ссылку на именованный канал;
    • case — разветвитель, направляющий входной поток в один или несколько дочерних каналов по условию;
    • fanout — разветвитель, безусловно направляющий входной поток во все дочерние каналы.

Пример секции routes:

routes:
  - input:
      plugin: someinput
    channel:
      pipe:
        - filter:
            plugin: somefilter
            config: ...
        - filter:
            plugin: somefilter
            config: ...
        - storage:
            storage_ref:
              name: mystorage
      output:
        plugin: someoutput
        config: ...

  - input:
      plugin: someinput
    channel:
      pipe:
        - filter:
            plugin: somefilter
            config: ...
      channel_ref:
        name: mychannel

  - input:
      plugin: someinput
    channel:
      pipe:
        - filter:
            plugin: somefilter
            config: ...
      fanout:
        - channel:
            ...
        - channel:
            ...
        - channel:
            ...

Пример использования элемента case:

- input:
    plugin: console
  channel:
    # Элемент case направляет входной поток в первый дочерний канал, подходящий по условию when.
    # Сообщение будет отброшено, если для него не удалось найти подходящий channel.
    # Этот факт будет учтен в health-счетчиках (Errors) и pipeline-счетчиках (DroppedMessages/DroppedBytes).
    # В логах агента будет сделана соответствующая запись с уровнем ERROR.
    # Данная ситуация рассматривается как нештатная.
    # Ее можно избежать, если добавить в case последним элементом catch all channel без фильтра when.
    case:
      # Внутри when можно описать условия на соответствие метаданных сообщения и сессии, по аналогии с фильтром match.
      - when:
          message:
            message-key: v1
          session:
            session-key: v2
        channel:
          output:
            plugin: dev_null

      # Внутри when любой из элементов message и session может отсутствовать.
      # Поддерживается свойство continue — не останавливать поиск подходящего канала, если условие when выполнено.
      # Таким образом можно направить вхоящие сообщения в несколько подоходящих каналов.
      - when:
          message:
            message-key: v1
        channel:
          output:
            plugin: dev_null
        continue: true

      # Элемент when может отсутствовать, в этом случае входной поток будет безусловно направлен в этот канал, если для него удалось создать сессию — никакой вложенный в него фильтр не отклонил создание сессии.
      - channel:
          output:
            plugin: dev_null

Секция channels

Секция содержит список именованных каналов. Перечисленные в этой секции каналы можно использовать в маршрутах доставки, обращаясь к ним по имени.

Пример секции channels:

channels:
  - name: named_channel
    channel:
      # Именованные каналы могут ссылаться на другие именованные каналы.
      channel_ref:
        name: other_named_channel

  - name: other_named_channel
    channel:
      output:
        plugin: dev_null

        # В любой плагин можно добавить идентификатор входа, выхода, хранилища и фильтра.
        # Этот идентификатор будет подставляться в метку plugin_id в мониторинге.
        # Также этим идентификатором будут отмечены соответствующие плагину записи в логе агента.
        id: my_dev_null_output

Пример маршрута доставки, использующий именованный канал:

- input:
    plugin: console
  channel:
    channel_ref:
      name: named_channel

Секция pipes

Секция содержит список именованных цепочек обработки. Перечисленные в этой секции цепочки можно использовать в каналах, обращаясь к ним по имени.

Пример секции pipes:

pipes:
  - name: named_pipe
    pipe:
      - filter:
          plugin: batch
          config:
              limit:
                bytes: 100kb
      - filter:
            plugin: assign
            config:
              message:
                - _payload: "{_timestamp:%b %d %H:%M:%S} {_payload}"

Пример маршрута доставки, использующий именованную цепочку обработки:

- input:
    plugin: console
  channel:
    pipe:
      pipe_ref:
        name: named_pipe
    output:
      plugin: debug

Секция main_thread_pool

Секция содержит конфигурацию потоков выполнения.

Описание параметров:

main_thread_pool:  # необязательно
  # Число потоков.
  threads: 1  # необязательный, по умолчанию 1

Секция agent_log

Секция содержит настройки логов самого агента. Могут быть переопределены через параметры командной строки.

Описание параметров:

agent_log:  # необязательный
  # Уровень логирования.
  # Возможные значения: EMERG, ALERT, CRITICAL_INFO, ERROR, WARNING, NOTICE, INFO, DEBUG, RESOURCES.
  priority: NOTICE  # необязательный, по умолчанию NOTICE

  # Писать логи в указанный файл.
  file: cerr  # необязательный, по умолчанию cerr (стандартный поток ошибок)

  # Ограничить скорость записи логов указанным значением.
  # Превышение будет отбрасываться, число отброшенных таким образом байт отражается в счетчике DroppedBytes в группе agent-log.
  rate_limit_bytes: null  # необязательно, по умолчанию не задан

Секция system

Разные системные настройки.

Описание параметров:

system:  # необязательный
  # Заблокировать вытеснение из памяти исполняемого кода агента с помощью системного вызова mlock.
  # Может помочь уменьшить задержки, так как при исполнении не будет major page faults для подгрузки кода с диска.
  lock_executable_in_memory: false  # необязательный, по умолчанию false

  # Установить лимит на объем используемой памяти с помощью системного вызова setrlimit.
  memory_limit: null  # необязательный, по умолчанию не задан

Секция flow_control

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

Секцию flow_control можно указывать для входов и для ссылок на хранилища (storage_ref).

Описание параметров:

flow_control:  # необязательный
  # Настройки буфера сессии.
  # Ограничение может быть выражено в байтах и в штуках сообщений.
  # При превышении любого из них срабатывает логика, заданная в атрибуте action.
  # Ограничение в штуках может быть полезно, когда на вход поступает много мелких сообщений, каждое из которых приводит к созданию большого выходного сообщения.
  inflight:
    # Размер буфера в байтах.
    limit: 10mb  # необязательный, по умолчанию 10mb

    # Размер буфера в штуках сообщений.
    limit_messages: null  # необязательный, по умолчанию не задан

    # Поведение при заполнении буфера:
    #   * backpressure — приостановить прием новых сообщений до освобождения буфера;
    #   * drop — отбрасывать новые сообщения, если они не помещаются в буфер.
    action: backpressure  # необязательный, по умолчанию backpressure

  # Ограничение на частоту создания новых сессий, в штуках новых сессий в секунду.
  # При превышении ограничения метод StartSession вернет TStartSessionResult::Throttled в поле Status.
  # Для хранилищ значение по умолчанию: отсутствует.
  # Для входов значение по умолчанию: 5.
  new_sessions_rate_limit: 5 # необязательный, по умолчанию 5 для input-ов, не поддерживается для storage_ref

Входы

Вход agent_metrics

Вход собирает метрики работоспособности Yandex Unified Agent.

Описание параметров:

- input:
    plugin: agent_metrics
    config:
      # Периодичность опроса источника данных.
      poll_period: 15s  # необязательный, по умолчанию 15 секунд

      # Неймсмпейс, в который нужно поместить метрики.
      # Если указан, будет добавлен префиксом к имени всех метрик.
      namespace: null  # необязательный, по умолчанию не задан

Вход metrics_pull

Вход опрашивает заданный URL с некоторой периодичностью и парсит из ответа метрики в указаном формате, например, в формате Prometheus.

Описание параметров:

  - input:
      plugin: metrics_pull
      config:
        # URL, на который будем ходить за данными метрик.
        url: http://localhost:12345  # обязательный

        # Формат получаемых сообщений. В настоящий момент поддерживается только значение prometheus.
        format:  # обязательный
          # Входящие сообщения имеют формат prometheus (https://github.com/prometheus/docs/blob/master/content/docs/instrumenting/exposition_formats.md).
          prometheus: {}

        # Периодичность опроса источника данных.
        # Моменты запуска выровнены по сетке размера poll_period, начиная с unix epoch.
        poll_period: 15s  # необязательный, по умолчанию 15 секунд

        # Неймсмпейс, в который нужно поместить метрики.
        # Если указан, будет добавлен префиксом с точкой к имени всех метрик.
        namespace: null  # необязательный, по умолчанию не задан

        # Число повторых попыток, если запрос завершился с ошибкой.
        retry_count: 0  # необязательный, по умолчанию 0

        # Задержка между повторными попытками.
        retry_delay: 1s  # необязательный, по умолчанию 1 секунда

        # Таймаут запроса, включая все повторые попытки.
        timeout: 5s  # необязательный, по умолчанию 5 секунд

        # Заголовки, которые нужно добавить к запросу.
        headers:  # необязательный, по умолчанию не задан
          h1: v1
          h2: v2

        # Имена заголовков HTTP-ответа, которые нужно сохранить в метаданных сообщения.
        capture_response_headers: []  # необязательный, по умолчанию не задан

        # HTTP-метод, который нужно использовать в запросе.
        # Возможные значения: GET, POST.
        http_method: GET  # необязательный, по умолчанию GET

Вход linux_metrics

Вход для сбора статистики использования системных ресурсов (процессор, память, сеть, диск) для Linux-совместимых операционных систем. Вход собирает значения метрик из procfs и sysfs.

Важно

Если агент запущен в Docker-контейнере, для мониторинга системных метрик хоста и дополнительных дисков, подключенных к хосту, передайте в контейнер пути до procfs, sysfs и точек монтирования дисков. Для этого воспользуйтесь командой docker run с параметром -v. Например, если дополнительный диск смонтирован в каталоге /data:

  docker run \
    -p 16241:16241 -it --detach --uts=host \
    --name=ua \
    -v /proc:/ua_proc \
    -v /data:/data \
    -e PROC_DIRECTORY=/ua_proc \
    -e FOLDER_ID=a1bs... \
    cr.yandex/yc/unified-agent

Описание параметров:

- input:
    plugin: linux_metrics
    config:
    # Периодичность сбора статистики.
    poll_period: 15s  # необязательный, по умолчанию 15 секунд

    # Директория со смонтированным procfs, из которой будут браться счетчики.
    # Если агент запущен в Docker-контейнере,  для мониторинга хоста передайте /proc хоста внутрь контейнера с помощью параметра -v.
    proc_directory: "/proc"  # необязательный, по умолчанию "/proc"

    # Директория со смонтированным sysfs, из которой будут браться счетчики.
    # Если агент запущен в Docker-контейнере, для мониторинга хоста передайте /sys хоста внутрь контейнера с помощью параметра -v.
    sys_directory: "/sys"  # необязательный, по умолчанию "/sys"

    # Список ресурсов, с которых нужно собирать статистику.
    # Ключ — одно из значений cpu, memory, network, storage, io, kernel.
    # Значение — степень детализации, одно из значений basic, advanced.
    resources:  # необязательный
        cpu: advanced  # необязательный, по умолчанию — basic

        memory: advanced  # необязательный, по умолчанию — basic

        network: advanced  # необязательный, по умолчанию — basic

        storage: advanced  # необязательный, по умолчанию — basic

        io: advanced  # необязательный, по умолчанию — basic

        kernel: advanced  # необязательный, по умолчанию — basic

Фильтры

Фильтр assign

Фильтр для присвоения метаданных сессии или сообщений.

Значение метаданных формируется при помощи шаблона. Синтаксис шаблона: {key:format|default}. Экранирование фигурных скобок осуществляется при помощи \: "\{\}".

Значение key:

  • _timestamp — временная метка сообщения;
  • _payload — тело сообщения;
  • key — метаданные с ключом key.

Если ключ метаданных не найден на уровне сообщения (в разделе message), будет выполнен поиск ключа в метаданных сессии. Если ключ не найден на уровне сессии, будет использовано значение по умолчанию ({_host|default_host}) или пустая строка, если значение по умолчанию не указано.

Так же в качестве значения key можно указывать макросы:

  • $host_name — локальное имя машины;
  • $short_host_name — локальное имя машины (краткое — до первой точки);
  • $env('name') — переменная окружения с именем name;
  • $file('name') — содержимое файла с именем name.

Поддерживается подстановка аргумента макроса из метаданных.
Например, в случае $file(name) имя файла будет взято из метаданных с ключом name.

Значение format — строка форматирования в формате strftime. Может быть указана только для _timestamp.

Значение default:

  • Определяет значение по умолчанию, если нет метаданных с таким ключом или пустой _payload.
  • Не может быть указан для _timestamp, так как _timestamp есть всегда.
  • Поддерживается для макросов $env и $file. Применяется, если указанный файл не найден или значение переменной окружения — пустая строка.
  • По умолчанию используется пустая строка.

Описание параметров:

- filter:
    plugin: assign
    config:
        # Должен быть указан хотя бы один из разделов message или session.

        # Значения, которые нужно присвоить в метаданные сообщения.
        # Внутри message должен быть список одноэлементных функций map, у которых ключ — имя метаданных, значение — шаблон форматирования.
        # Макросы в фигурных скобках в шаблоне могут содержать ключи метаданных ({_host}), и встроенные функции ({$file('test-file')}).
        # Если ключ метаданных не найден на уровне сообщения (в разделе `message`), будет выполнен поиск ключа в метаданных сессии.
        # Если ключ не найден на уровне сессии, будет использовано значение по умолчанию `({_host|default_host})` или пустая строка, если значение по умолчанию не указано.
        # Ниже приведено несколько примеров таких шаблонов.
        message:  # необязательный, по умолчанию не задан
            # Пример результата: 'Nov 27 21:03:24 test-host test-app:test_payload'.
            # Метка времени форматируется в соответствии с форматом strftime (http://man7.org/linux/man-pages/man3/strftime.3.html).
            # В этом примере значение _app 'test-app:', с двоеточием на конце — типичный результат разбора syslog-сообщения.
            - _payload: "{_timestamp:%b %d %H:%M:%S} {_host} {_app}{_payload}"

            # Подставить вместо $file значение из файла 'test-file'.
            # Если содержимое файла test-file равно test-content, то на выходе получится 'prefix_test-content_suffix'.
            - m1: "prefix_{$file('test-file')}_suffix"

            # Подставить значение из файла, имя которого можно взять из метаданных с ключом test-file-name.
            - m2: "prefix_{$file(test-file-name)}_suffix"

            # Подставить значение из переменной окружения 'test-env'.
            - m3: "prefix_{$env('test-env')}_suffix"

            # Подставить значение из переменной окружения, имя которой взять из метаданных с ключом test-env-name.
            - m4: "prefix_{$env(test-env-name)}_suffix"

            # Подставить имя хоста, на котором запущен агент.
            - m5: "$host_name"

            # Аналогично $host_name, только без домена — префикс до первой точки.
            # Например, если $host_name равен 'lbk-dev-02.search.yandex.net', то в $short_host_name будет значение 'lbk-dev-02'.
            - m6: "$short_host_name"

        # Значения, которые нужно присвоить в метаданные сессии.
        session:  # необязательный, по умолчанию не задан
            # Аналогично message.
            - m1: v1
            - m2: v2

Фильтр convert_metrics

Фильтр для преобразования метрик между разными форматами. Формат сообщений на входе берется из метаданных сессии с ключом _metrics_format (если он существует), либо из метаданных сообщения с тем же ключом (если он существует).

Если формат входящего сообщения определить не удалось (_metrics_format не указан ни на уровне сессии, ни на уровне сообщения), то входящее сообщение отбрасывается и счетчик RejectedMessages этого плагина увеличивается на один.

Описание параметров:

- filter:
    plugin: convert_metrics
    config:
        # Выходной формат, в который нужно преобразовать входящий набор метрик.
        # Должен быть указан ровно один из вложенных элементов.
        format:  # обязательный
          # Преобразовать в json формат Yandex Monitoring (https://cloud.yandex.ru/docs/monitoring/api-ref/MetricsData/write)
          json:
              # Нужно ли склеивать метрики с одним и тем же набором меток.
              # Возможные значения: default (не склеивать), merge_metrics (склеивать).
              merging_mode: default  # необязательный, значение по умолчанию default (не склеивать)

              # Нужно ли форматировать json в human readable (с переносами строк и отступами).
              # Задает размер отступов, если 0 — форматировать не нужно.
              indentation: 0  # необязательный, по умолчанию форматирование выключено

        # Набор меток, которые дополнительно нужно добавить к выходному набору метрик.
        labels:  # необязательный, по умолчанию не указан
            l1: v1
            l2: v2

        # Значение времени по умолчанию, которое нужно добавить к выходному набору метрик.
        # Поддерживаются два варианта синтаксиса значений этих параметров — абсолютный и относительный.
        # В абсолютном формате ожидается значение времени в формате ISO 8601.
        # Примеры: 2014-03-25 03:59:56.654563, 2012-11-23 11:12:13, 2012-11-23, 1990-03-15T15:10:12.
        # В относительном формате требуется указать смещение от одного из предопределенных значений:
        # * now — текущее время;
        # * today — начало текущих суток;
        # * yesterday — начало предыдущих суток;
        # * tomorrow — начало следующих суток.
        # Смещение состоит из произвольного числа временных дельт, разделенных операторами + или -.
        # Возможные значения для дельты:
        # * m — минута;
        # * h — час;
        # * d – сутки;
        # * w – неделя;
        # Например, --since yesterday оставит сообщения за вчера и сегодня, а --since now-5m --until now-5m+10s — за интервал в 10 секунд, который начался пять минут назад.
        # По умолчанию дельты отсчитываются от now, то есть вместо now-2m можно указать -2m.
        common_time: null  # необязательный, по умолчанию не задан

Фильтр filter_metrics

Фильтр позволяет сократить набор передаваемых метрик на основе значений меток.

- filter:
    plugin: filter_metrics
    config:
        # Условие на метрики, которые нужно оставить. Все остальные будут отфильтрованы.
        # Описание синтаксиса можно найти здесь https://cloud.yandex.ru/docs/monitoring/concepts/querying#selectors
        match: "{name=gauge-*}"  # обязательный

Фильтр match

Фильтрация сообщений по метаданным — фильтр пропускает только те сообщения, которые содержат все перечисленные метаданные.

Описание параметров:

- filter:
    plugin: match

    config:
        # Метаданные сессии в формате `ключ:значение`.
        session:  # необязательный
            a: b

        # Метаданные сообщения в формате `ключ:значение`.
        message:  # необязательный
            c: d
            e: f

        # В приведенной выше конфигурации фильтр будет пропускать только те сообщения, у которых:
        # * метаданные сессии содержат ключ "a" со значением "b";
        # * метаданные сообщения содержат ключ "c" со значением "d" и ключ "e" со значением "f" (обязательно оба).
        # При этом метаданные могут дополнительно содержать любые другие ключи.

Фильтр transform_metrics

Фильтр позволяет изменить метку внутри потока метрик.

Описание параметров:

- filter:
    plugin: transform_metric_label
    config:
        # Имя метки, которую нужно преобразовать.
        label: sensor  # обязательный

        # Добавить префикс к значению метки.
        add_value_prefix: ua  # необязательный

        # Переименовать метку.
        rename_to: name  # необязательный

        # Разделитель, который нужно использовать между добавляемым префиксом (add_value_prefix) и текущим значением метки.
        delimiter: .  # необязательный, по умолчанию '.'

Хранилища

Хранилище fs

Файловое хранилище. Сообщения сохраняются в партициях. Партиции — это директории, содержащие файлы-сегменты с данными сообщений, а также файлы с метаданными.

Важно

Не рекомендуется использовать файловое хранилище вместе с опцией монтирования файловой системы nobarrier. При потере питания не гарантируется сохранность данных, может потребоваться ручное вмешательство.

Описание параметров:

storages:  # необязательный
  # Хранилище на основе файловой системы.

  # Имя хранилища. По этому имени на хранилище можно сослаться из цепочек преобразований при помощи storage_ref.
  # На одно хранилище можно сослаться только 1 раз.
- name: main  # обязательный
  # Имя плагина. Пока поддерживается только плагин fs для бинарного хранилища в файловой системе.
  plugin: fs  # обязательный

  config:
    # Директория с данными хранилища.
    # В ней создаются поддиректории для партиций.
    directory: ./data/storage  # обязательный

    # Максимальный размер партиции.
    # По умолчанию в хранище есть только одна партиция с именем default.
    # Новая партиция создается только если пользователь явно этого потребовал, указав имя партиции в ключе _partition в метаданных сессии.
    # В основных сценариях партиция только одна, поэтому этот параметр можно считать лимитом на размер всего хранилища.
    max_partition_size: 10mb  # обязательный

    # Директория для хранения служебной информации хранилища.
    # По умолчанию — .state внутри directory
    state_directory: {directory} / .state  # необязательный, по умолчанию .state внутри directory

    # Максимальный размер сегмента (одного файлика) внутри партиции.
    # По умолчанию — десятая часть размера партиции.
    max_segment_size: {max_partition_size} / 10  # необязательный, по умолчанию десятая часть от max_partition_size

    # Размер блока для записи.
    # Для снижения накладных расходов на системные вызовы перед вызовом write сообщения группируются в блок.
    # Вызов write осуществляется, если размер блока превышает указанный.
    block_flush_size: 1mb  # необязательный, по умолчанию 1mb

    # Время жизни блока для записи.
    # Вызов write будет осуществляться, если с момента поступления первого сообщения в блок прошло больше указанного времени.
    block_flush_period: 10ms  # необязательный, по умолчанию 10ms

    # Размер буфера для вызова syscall read.
    # По умолчанию совпадает с block_flush_size.
    read_buffer_size: {block_flush_size}  # необязательный, по умолчанию совпадает с block_flush_size

    # Время хранения информации о сессии.
    # Как только входящая сессия будет закрыта, хранилище перестанет хранить информацию о об этой сессии.
    # Соответствие sessionId->last_seq_no и метаданные сессии будут удалены.
    # Сессия удаляется только в том случае, если все данные по ней были записаны в выходы.
    session_retention_time: 1h  # необязательный, по умолчанию 1h

    # Время хранения данных партиции.
    # Партиция будет удалена через указанное время, если:
    # * все ее данные записаны в выходы и по ним получены подтверждения;
    # * нет активных сессий, пишущих в эту партицию.
    partition_retention_time: 1h  # необязательный, по умолчанию: 1h

    # Частота выполнения проверки на время хранения session_retention_time и partition_retention_time.
    retention_check_period: 1m  # необязательный, по умолчанию 1m

    # Частота выполнения fsync.
    # Чем чаще выполняется fsync, тем меньше данных нужно проверять при восстановлении после сбоя, и тем быстрее произойдет запуск агента.
    checkpoint_period: 1s  # необязательный, по умолчанию не задан

    # Параметр описывает условия, при которых сегменты с данными сохраняются после получения подтверждения от выхода.
    # Когда ни одно условие не выполнено, сегменты удаляются в порядке от старых к новым.
    # Под старым сегментом здесь понимается противоположный от того, в который запись идет на данный момент.
    #
    # Условия проверяются:
    # * в момент получения подтверждения от выхода;
    # * в момент поступления новых данных;
    # * регулярно с периодичностью retention_check_period.
    #
    # На уровне партиции поддерживаются счетчики TrailingMessageAgeMs и TrailingSegmentAgeMs.
    # TrailingMessageAgeMs определяется по timestamp первого сообщения самого старого сегмента.
    # Этот счетчик примерно (без учета возможной немонотонности timestamp) показывает период времени, за который в партиции имеются данные.
    # TrailingSegmentAgeMs определяется аналогично по следующему за ним сегменту.
    # Этот счетчик показывает, когда последний сегмент будет удален (при достижении значения свойства by_age).
    # Значения обоих счетчиков — в миллисекундах.
    # Если в партиции нет ни одного сегмента, оба счетчика равны нулю.
    # Если в партиции только один сегмент, значение TrailingSegmentAgeMs равно нулю.
    #
    # Параметр не задан по умолчанию, т.е. самый старый сегмент удаляется при получении подтверждения от выхода для последнего сообщения этого сегмента.
    data_retention:  # необязательный
      # Сегмент не удаляется, пока в нем есть более свежие сообщения.
      # Актуальность сообщений определяется по времени в поле timestamp первого сообщения предпоследнего сегмента.
      # В партиции будут храниться данные примерно за указанный период.
      by_age: 10d  # необязательный, по умолчанию не задан

      # Сегмент не удаляется, пока размер данных партиции, исключая собственный размер сегмента, остается меньше указанного.
      # То есть размер партиции будет поддерживаться не меньше указанного.
      # Если указать by_size: max, то данные будут удаляться только по достижении лимита на размер партиции.
      by_size: 500mb  # необязательный, по умолчанию не задан

    # Уровень логирования, который будет использован при удалении неподтвержденных данных.
    # Обычно мониторинг агента смотрит на значение счетчика `Errors` — общее число событий внутри агента, залогированных с уровнем ERROR.
    # Если переполнение хранилища — потенциально возможный сценарий (например, в агент записываются данные интенсивнее, чем лимит, указанный в параметре `new_sessions_rate_limit` секции `flow_control`), этим параметром можно отключить зажигание алертов в этом случае.
    # Возможные значения: EMERG, ALERT, CRITICAL_INFO, ERROR, WARNING, NOTICE, INFO, DEBUG, RESOURCES.
    unacknowledged_eviction_log_priority: ERROR  # необязательный, по умолчанию ERROR

Выходы

Выход debug

Отладочный выход — выводит поступающие сообщения в файл или в консоль.

В хранилище пока не поддерживается локальный просмотр данных. Вы можете настроить выгрузку данных в файл через этот выход. Ротацию можно настроить через утилиту logrotate. Чтобы агент начал записывать логи в новый файл, воспользуйтесь методом reopen_file. Для этого потребуется примерно такая конфигурация:

status:
  port: 16301

output:
  plugin: debug
  id: my_output_id
  config:
    file_name: ./data/output
    delimiter: "\n===\n"
    _test:
      register_test_handlers: true

Описание параметров:

- channel:
    output:
        plugin: debug
        config:
            # Должно быть указано одно из свойств file_name или directory.

            # Имя файла, в который будут записываться сообщения.
            # Для вывода в консоль укажите значение "/dev/stdout".
            file_name: out.txt  # необязательный, по умолчанию не задан

            # Имя директории. Если указано, данные каждой сессии будут записываться в отдельный файл в этой директории с именем, равным идентификатору сессии.
            directory: output_directory  # необязательный, по умолчанию не задан

            # Разделитель сообщений в файле, например "\n".
            delimiter: null  # обязательный

Выход dev_null

Отладочный «пустой» выход — выбрасывает поступающие сообщения.

Не содержит параметров.

Выход yc_metrics

Выход для записи метрик в Yandex Monitoring API.

Описание параметров:

- channel:
    output:
        plugin: yc_metrics
        config:
        # URL, на который будут отправляться метрики.
        url: https://monitoring.api.cloud.yandex.net/monitoring/v2/data/write  # необязательный, по умолчанию https://monitoring.api.cloud.yandex.net/monitoring/v2/data/write

        folder_id: b1ge2vt0gml6ce48qcks  # обязательный, идентификатор каталога

        # Настройки IAM-аутентификации.
        iam:  # обязательный
            # Должен быть указан один из элементов cloud_meta или jwt.

            # Если указан, IAM-токен берется из сервиса метаданных.
            cloud_meta: {}  #необязательный, по умолчанию не задан

            # Если указан, JWT обменивается на IAM-токен.
            jwt:  #необязательный, по умолчанию не задан
            # Имя файла с параметрами JWT в формате, который возвращает команда `yc iam key create`.
                file: "jwt_params.json"  # обязательный

                endpoint: iam.api.cloud.yandex.net  # необязательный, по умолчанию iam.api.cloud.yandex.net

                refresh_period: 1h  # необязательный, по умолчанию 1h

                request_timeout: 10s  # необязательный, по умолчанию 10s

        # Число повторых попыток, если запрос завершился с ошибкой.
        # Если за указанное число запрос так и не был выполнен успешно (то есть не был получен ответ со статусом 200), сообщение отбрасывается, то есть по нему формируется подтверждение в сторону агента.
        # Отброшенные таким образом сообщения учитываются в счетчике DroppedMessages этого плагина, а также отображаются в общих health-счетчиках MessagesLost и BytesLost.
        retry_count: inf  # необязательный, по умолчанию max_int, то есть сообщения отбрасываться не будут

        # Задержка между повторными попытками.
        retry_delay: 1s  # необязательный, по умолчанию 1 секунда

        # Таймаут запроса, включая все повторые попытки.
        timeout: inf  # необязательный, по умолчанию max_int секунд, то есть сообщения отбрасываться не будут

        # Таймаут на одну попытку.
        request_timeout: 1s  # необязательный, по умолчанию одна секунда

Выход yc_logs

Выход для отправки метрик в Yandex Cloud Logging по протоколу grpc.

Примечание

Агент не гарантирует отсутствие дубликатов сообщений в целевой системе, но делает все возможное, чтобы их не было. Дубликаты могут возникать при остановке и последующем повторном запуске.

Описание параметров:

- channel:
    output:
        plugin: yc_metrics
        config:
        # URL, на который будут отправляться метрики.
        url: https://monitoring.api.cloud.yandex.net/monitoring/v2/data/write  # необязательный, по умолчанию https://monitoring.api.cloud.yandex.net/monitoring/v2/data/write

        folder_id: b1ge2vt0gml6ce48qcks  # обязательный, идентификатор каталога

        # Настройки IAM-аутентификации.
        iam:  # обязательный
            # Должен быть указан один из элементов cloud_meta или jwt.

            # Если указан, IAM-токен берется из сервиса метаданных.
            cloud_meta: {}  #необязательный, по умолчанию не задан

            # Если указан, JWT обменивается на IAM-токен.
            jwt:  #необязательный, по умолчанию не задан
            # Имя файла с параметрами JWT в формате, который возвращает команда `yc iam key create`.
                file: "jwt_params.json"  # обязательный

                endpoint: iam.api.cloud.yandex.net  # необязательный, по умолчанию iam.api.cloud.yandex.net

                refresh_period: 1h  # необязательный, по умолчанию 1h

                request_timeout: 10s  # необязательный, по умолчанию 10s

        # Число повторных попыток, если запрос завершился с ошибкой.
        # Если за указанное число запрос не был выполнен успешно (не получен ответ со статусом 200), сообщение отбрасывается. По этому сообщению формируется подтверждение в сторону агента
        # Отброшенные таким образом сообщения учитываются в счетчике DroppedMessages этого плагина, а также отображаются в общих health-счетчиках MessagesLost и BytesLost.
        retry_count: inf  # необязательный, по умолчанию max_int, то есть сообщения отбрасываться не будут

        # Задержка между повторными попытками.
        retry_delay: 1s  # необязательный, по умолчанию 1 секунда

        # Таймаут запроса, включая все повторые попытки.
        timeout: inf  # необязательный, по умолчанию max_int секунд, то есть сообщения отбрасываться не будут

        # Таймаут на одну попытку.
        request_timeout: 1s  # необязательный, по умолчанию одна секунда

Примеры

Примеры конфигураций приведены в разделе Работа с метриками.

Была ли статья полезна?

Language / Region
© 2022 ООО «Яндекс.Облако»
В этой статье:
  • Файлы конфигурации
  • Импорт конфигурационных файлов
  • Вывод и валидация итоговой конфигурации
  • Директивы конфигурации
  • Секция status
  • Секция storages
  • Секция routes
  • Секция channels
  • Секция pipes
  • Секция main_thread_pool
  • Секция agent_log
  • Секция system
  • Секция flow_control
  • Входы
  • Фильтры
  • Хранилища
  • Выходы
  • Примеры