Перейти к основному содержимому
Версия: 3.2

Управление конфигурациями Logstash

Описание

Роль управления конфигурациями Logstash не включает перезагрузку сервиса Logstash, не изменяет параметры в файле jvm.options, в том числе не редактирует размер heap.

Роль конфигурирует следующие файлы:

  • logstash.yml
  • pipelines.yml
  • конфигурационные файлы пайплайнов

При изменении в конфигурационных файлах создаются резервные копии. Также осуществляется поиск резервных копий и производится удаление бэкапов файлов старше 1 дня.

При отключении пайплайна на хосте конфигурационный файл переименовывается с расширением .bkp и не удаляется.

Параметры роли

Значения по умолчанию указаны относительно рекомендаций Smart Monitor.

var_logstash_pipelines_list

Объект (YAML) с описанием параметров пайплайнов Logstash. Обычно используется для группы хостов (влияет на приоритеты и последовательность объединения параметров). Поддерживает объединение с параметрами, начинающимися на var_logstash_pipelines_list_, например: var_logstash_pipelines_list_syslog var_logstash_pipelines_list_win_log

host_var_logstash_pipelines_list

Объект (YAML) с описанием параметров пайплайнов Logstash. Обычно используется для описания параметров хоста (влияет на приоритеты и последовательность объединения параметров). Поддерживает объединение с параметрами, начинающимися на host_var_logstash_pipelines_list_, например: host_var_logstash_pipelines_list_syslog host_var_logstash_pipelines_list_win_log

var_logstash_files

Объект (YAML) с основными параметрами Logstash

ПеременнаяЗначение по умолчаниюОписание
var_logstash_files.path_confдиректория расположения конфигурации Logstash, по умолчанию/app/logstash/config
var_logstash_files.path_logдиректория нахождения логов Logstash, по умолчанию/app/logs/logstash/logstash-plain.log
var_logstash_files.dir_subcfgназвания директории расположения файлов конфигураций пайплайнов, обычноconf.d
var_logstash_files.ownerимя владельца файлов, по умолчанию"logstash"
var_logstash_files.groupимя группы владельцев файлов, по умолчанию"logstash"
var_logstash_files.modeпривилегии на создаваемые файлы, по умолчанию"0644"
var_logstash_files.folder_modeпривилегии на создаваемые директории, по умолчанию"0755"

Параметры файла logstash.yml

Далее следуют параметры (объекты YAML), относящиеся к глобальным параметрам Logstash и прописываются в файле logstash.yml. Разделено на 5 объектов только для группировки части параметров по "общим признакам" и соответствующим комментарием в файле logstash.yml.

var_logstash_node_settings

Объект (YAML) с параметрами, относящиеся к текущему узлу, обычно включает следующие параметры:

ПеременнаяЗначение по умолчаниюОписание
node.nameимя узла, значение по умолчаниюsmosed-logstash
config.reload.automaticперезагружать ли автоматически конфигурацию Logstash pipelinefalse
config.reload.intervalвремя проверки изменения конфигураций для автоматического применения конфигурации3s

var_logstash_path_settings

Объект (YAML) с параметрами, относящиеся к текущему узлу и указанию директорий, обычно включает следующие параметры:

ПеременнаяЗначение по умолчаниюОписание
path.dataдиректория расположения данных/app/data/logstash
path.logsдиректория расположения логов/app/logs/logstash

var_logstash_pipeline_settings

Объект (YAML) с параметрами, относящиеся к глобальным параметрам pipeline, обычно включает следующие параметры:

ПеременнаяЗначение по умолчаниюОписание
pipeline.orderedуправление порядком событий пайплайнаauto
pipeline.separate_logsсохранение логов пайплайнов в отдельные файлыtrue

var_logstash_queue_settings

Объект (YAML) с параметрами, относящиеся к параметрам работы с очередями, обычно включает следующие параметры:

ПеременнаяЗначение по умолчаниюОписание
queue.typeтип буфера для хранения буфера событийmemory
queue.page_capacityразмер страницы при файловом типе буфера событий64mb
queue.max_eventsколичество необработанных событий в очереди для включения буфера файлового типа0
queue.max_bytesмаксимальное значение буфера файлового типа в байтах1024mb
queue.checkpoint.acksмаксимальное количество событий с подтверждением перед форсированием при файловом типе очереди1024
queue.checkpoint.writesмаксимальное количество записанных событий перед форсированием при файловом типе очереди1024
queue.checkpoint.intervalинтервал в миллисекундах принудительной установки контрольной точки при файловом типе очереди1000

var_logstash_dead_letter_queue_settings

Объект (YAML) с параметрами, относящиеся к параметрам работы с очередью недоставленных сообщений, обычно включает следующие параметры:

ПеременнаяЗначение по умолчаниюОписание
dead_letter_queue.enableвключает очередь для недоставленных сообщенийfalse
dead_letter_queue.max_bytesразмер очереди недоставленных сообщений в байтах1024mb
dead_letter_queue.flush_intervalпериод записи очереди в файл в миллисекундах5000

Глобальные параметры Logstash

Глобальные параметры Logstash располагаются в файле <PATH_TO_LOGSTASH_CONFIG>/logstash.yml, для удобства визуально разбиты на 5 групп:

Если планируется изменить какой-нибудь параметр в группе, то нужно будет указать все из значения по умолчанию и изменить необходимые. Указывать параметры нужно по правилам YAML. Некоторые параметры имеют значения по умолчанию в логике Logstash, подробнее можно прочитать в официальной документации.

Например:

var_logstash_queue_settings:
queue.type: persistent
queue.page_capacity: 64mb
queue.max_events: 0
queue.max_bytes: 1024mb
queue.checkpoint.ack s: 1024
queue.checkpoint.writes: 1024
queue.checkpoint.interval: 1000

Будет использован другой тип очереди с перечисленными параметрами. Если не указать ни одной переменной группы, то настройка logstash.yml будет игнорироваться.

Рекомендация по структуре файлов

Согласно правилам Ansible можно вынести параметры для группы хостов в директорию group_vars и для определённых хостов в директорию host_vars. Внутри этих директорий может быть файл с одноименным именем группы или хоста соответственно.

Вместо файла может быть одноименная директория, внутри которой могут располагаться файлы, которые по правилам Ansible соберутся в единый файл при выполнении плейбука.

Например, есть файл инвентаризации hosts, в нём есть описание группы _example_, а также __example_. Во втором случае все параметры указаны в одном файле, в первом - разбиты на файлы в одноименной директории. В примере для хостов не используются директории, только файлы с параметрами, относящиеся к определённому хосту.

.
├── group_vars
│   ├── __example_
│   └── _example_
│   ├── connect
│   ├── logstash_base
│   ├── pipeline__default
│   ├── pipeline_apache
│   ├── pipeline_cisco_ios
│   └── pipeline_os
├── host_vars
│   ├── test1
│   ├── test2
│   ├── test3
│   └── test4
└── hosts
Обратите внимание!

Мы рекомендуем указывать дополнительные параметры для групп и хостов в директориях и разбивать параметры на файлы

Настройки каждого пайплайна рекомендуется выносить в отдельный файл, как приведено выше в примере. Называть файлы рекомендуется с ключевого слова pipeline_, далее должно следовать имя пайплайна (id в pipelines.yml).

Общие параметры пайплайнов вынесены в отдельный файл pipeline__default, использовано специально двойное подчёркивание, чтобы файл выделялся в списке. Подробнее по общим параметрам в следующем разделе.

Описать определённый пайплайн можно в параметрах (подробнее в следующем разделе) или создать шаблон в формате JINJA2 в директории templates/conf.d, например, в примере ниже при указании пайплайна wineventlog будет использован шаблон файла wineventlog.conf.j2. Так же здесь присутствует шаблон для пайплайна test, для всех остальных пайплайнов будет использован шаблон default_pipeline.j2.

.
└── templates
├── conf.d
│   ├── common
│   ├── default_pipeline.j2
│   ├── test.conf.j2
│   └── wineventlog.conf.j2
├── logstash.yml.j2
└── pipelines.yml.j2

Пример содержимого файла шаблона пайплайна:

input {
{% include 'common/input.j2' %}
}

filter {
json{
source => "message"
}

date {
match => [ "timestamp" , "ISO8601"]
}

mutate{
remove_field => ["path"]
}
}

output {
{% include 'common/output.j2' %}
}

В данном примере блоки input и output будут заполняться из параметров, описанных в конфигурациях, а блок filter будет игнорироваться и использован из данного шаблона.

Настройка пайплайнов

Существует несколько уровней конфигурации пайплайнов, приведены в порядке уменьшения приоритета:

  • на уровне хоста у определённого пайплайна
  • на уровне хоста default
  • на уровне группы у определённого пайплайна
  • на уровне группы default
Обратите внимание!

При запуске плейбука, все объекты (параметры) объединяются в указанном приоритете, если в параметре был список - то он полностью заменяется списком более приоритетного уровня.

Для описания параметров пайплайнов используются два объекта (переменные):

  • var_logstash_pipelines_list - используется в группах хостов
  • host_var_logstash_pipelines_list - используется в хостах

При разделении параметров групп и хостов на файлы согласно нашей рекомендации вышеуказанные объекты заменяются на множество объектов, к их имени добавляется _<id_pipeline>, где <id_pipeline> должен быть заменён на уникальный id, например: var_logstash_pipelines_list_test var_logstash_pipelines_list_apache host_var_logstash_pipelines_list_win_log

Для дефолтных настроек зарезервированы следующие объекты: var_logstash_pipelines_list_default host_var_logstash_pipelines_list_default

Обратите внимание!

Объекты рекомендуются размещать в соответствующих файлах с именем pipeline_<id_pipeline>.

Внутри соответствующего объекта должен быть объект с именем <id_pipeline>. Например, для описания default должен быть создан файл pipeline__default, внутри него должны быть следующие объекты:

var_logstash_pipelines_list_default:
default:

Для пайплайна apache должен быть создан файл pipeline_apache, внутри которого будут объекты:

var_logstash_pipelines_list_apache:
apache:

Внутри объектов могут быть следующие объекты:

Объект default

Объект default используется для указания одинаковых параметров для всех пайплайнов. Совпадающие параметры или объекты плагинов по имени будут заменены данными из более приоритетных. Внутри объекта можно указать сразу все общие параметры для разных плагинов, при описании плагинов блоков input, output параметры из default будут применяться только при указании соответствующего плагина.

Например:

input:
file:
add_field:
'[logstash][fil1]': 'fsdbfhsdbfgdfsfgbdfbg'
'[logstash][fil2]': 'fsdbfhsdbfgdfsfgbdfb2'
'[logstash][fil3]': 3423
codec:
cef:
ecs_compatibility: 'disabled'
relp:
codec: 'cef {}'

В данном примере указаны плагины блока input file и relp, везде в пайпланах, где будет указан один из этих плагинов будут добавлены соответствующих параметры.

Объект copy_files

Объект создан специально для случае, когда нужно скопировать определённые файлы как есть на сервер. Имеет следующий синтаксис:

copy_files:
- source: 'vbtest/apache.sql'
destination: '/app/logstash/config/conf.d/apache/'
- source: 'vbtest/apache2.sql'
destination: '/app/logstash/config/conf.d/apache/'

Директории создаются автоматически если не были созданы.

Объект configs

В этом объекте описываются параметры для пайплайна, которые прописываются в файле pipelines.yml. Параметры указываются согласно синтаксису YAML, используются параметры из документации Logstash.

Пример:

configs:
pipeline:
workers: 5
batch:
size: 125
modules: |
- name: MODULE_NAME1
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE
var.PLUGIN_TYPE2.PLUGIN_NAME2.KEY1: VALUE
var.PLUGIN_TYPE3.PLUGIN_NAME3.KEY1: VALUE
- name: MODULE_NAME2
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE

Результатом будет:

- pipeline.id: apache
path.config: '/app/logstash/config/conf.d/apache.conf'
pipeline.workers: 5
pipeline.batch.size: 125
modules:
- name: MODULE_NAME1
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE
var.PLUGIN_TYPE2.PLUGIN_NAME2.KEY1: VALUE
var.PLUGIN_TYPE3.PLUGIN_NAME3.KEY1: VALUE
- name: MODULE_NAME2
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE

Объект input

В этом объекте могут быть следующие объекты:

  • clear_text
  • LDAPSearch
  • exec
  • kafka
  • snmp
  • udp
  • file
  • opensearch
  • syslog
  • beats
  • elasticsearch
  • jdbc
  • relp
  • tcp

clear_text специальный объект, подробнее описан в объекте filter.

Для остальных объектов можно использовать параметры одноименных плагинов из документации ElasticSearch Logstash input plugin.

Если в пайплайне используется один input plugin, то можно указывать параметры плагина в синтаксисе YAML, например:

input:
file:
path: '/app/generator/data/generated/apc_snmp_generated.log'
start_position: 'beginning'
sincedb_path: '/dev/null'

Если в пайплайне используется несколько одинаковых input plugin, то можно указать списком, например:

input:
relp:
- id: 'cef_erpv1'
port: 10343
codec: 'cef { reverse_mapping => false }'
- id: 'cef_kredan'
port: 10804
codec:
json:
ecs_compatibility: 'v8'
- id: 'cef_sasid'
port: 11655

Дополнительные параметры из объекта default.relp будут добавлены в каждый плагин из примера выше.

Объект filter

Для объекта может быть только параметр clear_text. Текст внутри параметра будет добавлен как есть. Пример:

clear_text: |
grok {
match => { "message" => "%{IP_OR_HOST:clientip} %{DATA:ident}" }
}
date {
match => [ "timestamp" , "dd/MMM/yyyy:HH:mm:ss Z" ]
}
mutate{
remove_field => ["path"]
}

Стоит обратить внимание на вертикальную черту "|", а также на отступы внутри параметра clear_text согласно правилам YAML.

Объект output

В этом объекте могут быть следующие объекты:

  • clear_text
  • http
  • stdout
  • udp
  • elasticsearch
  • opensearch
  • tcp

Можно указать несколько разных плагинов, например:

input:
file:
path: ['/app/generator/data/generated/apache_generated.log', '/var/log/test.log']
check_archive_validity: true
start_position: 'beginning'
exclude:
- test1
- test2
sincedb_path: '/dev/null'
add_field:
'[logstash][fil1]': 'yyyyy'
'[logstash][fil5]': 1923
kafka:
topics: ['top1', 'top2']

В примере выше будет два плагина file и kafka с описанными параметрами.

Объект codec

Некоторые плагины имеют параметр codec, его можно указать строкой:

input:
relp:
- id: 'cef_erpv1'
port: 10343
codec: 'cef { reverse_mapping => false }'

Можно указывать параметры как внутри объекта:

input:
relp:
id: 'cef_erpv1'
codec:
json:
ecs_compatibility: 'v8'

Указание параметров codec как объекты возможно только для следующих объектов:

  • cef
  • csv
  • json
  • json_lines
  • plain

Примеры

Конфигурационные файлы роли Ansible

Файл pipeline__default:

var_logstash_pipelines_list_default:
default:
output:
opensearch:
hosts:
- 'https://172.16.0.174:9200'
- 'https://172.16.0.175:9200'
index_region: 'testregion'
user: 'logstash'
password: '{ES_PWD}'
ssl: true
cacert: '/app/logstash/config/ca-cert.pem'
ilm_enabled: false
input:
relp:
codec: 'cef {}'

Файл pipeline_test:

var_logstash_pipelines_list_test:
test:
output:
opensearch:
input:
file:
path: '/app/generator/data/generated/cisco_ios_generated.log'
start_position: 'beginning'
sincedb_path: '/dev/null'
filter:
clear_text: |
grok {
match => ["message", "%{DATA:timestamp} %{IPV4:ip} %{INT:number}:"]
}

Файл pipeline_test2:

var_logstash_pipelines_list_test2:
test2:
output:
opensearch:
hosts:
- 'https://172.16.0.174:9200'
user: 'admin'
input:
relp:
id: 'cef_erpv1'
port: 10343

Результаты после выполнения плейбука Ansible

Файл pipelines.yml:

- pipeline.id: test
path.config: '/app/logstash/config/conf.d/test.conf'

- pipeline.id: test2
path.config: '/app/logstash/config/conf.d/test2.conf'

Файл conf.d/test.conf

input {
file {
path => "/app/generator/data/generated/cisco_ios_generated.log"
sincedb_path => "/dev/null"
start_position => "beginning"

}
}

filter {
grok {
match => ["message", "%{DATA:timestamp} %{IPV4:ip} %{INT:number}:"]
}
}

output {
opensearch {
cacert => "/app/logstash/config/ca-cert.pem"
hosts => ["https://172.16.0.174:9200", "https://172.16.0.175:9200"]
ilm_enabled => "false"
index => "test_testregion"
password => "{ES_PWD}"
ssl => true
user => "logstash"

}
}

Файл conf.d/test2.conf

input {
relp {
port => 10343
codec => cef {}
id => "cef_erpv1"

}
}


output {
opensearch {
cacert => "/app/logstash/config/ca-cert.pem"
hosts => ["https://172.16.0.174:9200"]
ilm_enabled => "false"
index => "test2_testregion"
password => "{ES_PWD}"
ssl => true
user => "admin"

}
}