Конфигурирование
Данный раздел описывает настройку 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
можно импортировать другие конфигурационные файлы. Значение директивы — строка или массив строк, каждая строка раскрывается при помощи функции globimport
, а внутри одной директивы — в лексикографическом порядке по именам файлов.
При импорте файлов конфигурации работают правила:
- Разделы
status
иmain_thread_pool
будут взяты из последнего импортируемого файла. - Разделы
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
Секция содержит список маршрутов доставки.
Маршрут доставки состоит из следующих элементов:
Вход состоит из следующих элементов:
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
Unified Agent собирает метрики только тех устройств хранения, которые смонтированы как /dev/..
. В частности, не поддерживаются файловые хранилища Compute Cloud.
Важно
Если агент запущен в 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=a1bs81qpemb4******** \
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 (../../../api-ref/MetricsData/write.md)
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://yandex.cloud/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_metric_label
Фильтр позволяет добавлять к метрикам новые метки, удалять и заменять существующие. В качестве значения метки можно указать фиксированную строку или текстовое выражение с использованием других меток. С помощью выражения match
можно ограничить набор метрик, к которым применяется преобразование.
Описание параметров:
- filter:
plugin: transform_metric_labels
config:
# Ограничить применение фильтра только теми метриками, которые удовлетворяют данному условию.
# Описание синтаксиса можно найти здесь https://yandex.cloud/ru/docs/monitoring/concepts/querying#selectors
match: "{name=gauge-*}" # необязательный параметр, по умолчанию не задан, фильтр применяется ко всем метрикам
# Описание преобразований меток в формате "имя метки: выражение".
# Имя метки — метка, в которую присваиваем новое значение.
# Выражение — текстовая строка с описанием нового значения.
# В этой строке с помощью синтаксиса "{my_label}" можно ссылаться на текущие значения меток,
# включая ту метку, которая изменяется в данный момент. В таком случае будет использовано ее предыдущее значение.
# Преобразования выполняются в заданном порядке, в последующих выражениях
# можно ссылаться на результаты предыдущих.
# Синтаксис выражений аналогичен тому, который используется в фильтре assign.
# С помощью {my_label|default_value} можно указать значение по умолчанию, если метка my_label не найдена.
# Чтобы удалить метку, используйте синтаксис my_label: "-".
labels:
- l2: "prefix_{l1}_suffix" # обязательный
- l3: "prefix2_{l2}_s_{l1|default_value}" # обязательный
- l4: "-" # обязательный
Хранилища
Хранилище 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: b1ge2vt0gml6******** # обязательный, идентификатор каталога
# Настройки 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_logs
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: b1ge2vt0gml6******** # обязательный, идентификатор каталога
# Настройки 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 # необязательный, по умолчанию одна секунда
Примеры
Примеры конфигураций приведены в разделе Работа с метриками.