Диагностика проблем Smart Monitor Data Collector

В статье описана диагностика Smart Monitor Data Collector (далее - Data Collector). Примеры проверены на версии 8.9.0. Ответы API, представленные как примеры исправной работы, получены на тестовом стенде.

Условные обозначения

• DATA_COLLECTOR_HOME - домашняя директория Data Collector (LS_PATH_HOME), обычно /app/logstash/
• DATA_COLLECTOR_DATA - директория данных Data Collector (LS_PATH_DATA, параметр path.data), включая очередь и Dead Letter Queue; обычно отдельная директория /app/data/logstash/, а не поддиректория ${DATA_COLLECTOR_HOME}
• DATA_COLLECTOR_LOGS - директория журналов Data Collector (LS_PATH_LOGS, параметр path.logs); обычно отдельная директория /app/logs/logstash/
• PIPELINE_ID - идентификатор пайплайна; задается параметром pipeline.id в ${DATA_COLLECTOR_HOME}/config/pipelines.yml, а не в файле конфигурации пайплайна .conf

к сведению

При стандартной установке Smart Monitor DATA_COLLECTOR_DATA и DATA_COLLECTOR_LOGS находятся в отдельных директориях, не вложенных в DATA_COLLECTOR_HOME. Фактические пути указаны в ${DATA_COLLECTOR_HOME}/config/logstash.yml (параметры path.data и path.logs) либо в ExecStart и Environment юнита logstash.service. Значения по умолчанию задаются при установке (см. Установка Smart Monitor Data Collector).

Команды в статье используют перечисленные переменные. По умолчанию в сеансе они не заданы: перед выполнением команд замените переменные фактическими путями или задайте их в сеансе:

export DATA_COLLECTOR_HOME=/app/logstash
export DATA_COLLECTOR_DATA=/app/data/logstash
export DATA_COLLECTOR_LOGS=/app/logs/logstash

Диагностический API Data Collector

Data Collector предоставляет отдельный HTTP API для диагностики. По умолчанию он доступен локально на хосте Data Collector через порт 9600.

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

Диагностический API Data Collector (путь _node/stats/..., порт 9600) не связан с API Data Storage (путь _nodes/stats/..., порт 9200, доступен через Консоль разработчика). Запрос метрики flow через API Data Storage возвращает ошибку:

{"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/_nodes/stats/flow] contains unrecognized metric: [flow]"}],"status":400}}

Выполняйте диагностические запросы непосредственно на хосте Data Collector, а не через Консоль разработчика.

Проверьте доступность API:

curl -s "http://localhost:9600?pretty"

Пример ответа при исправной работе службы:

{
  "host": "sm-logstash",
  "version": "8.9.0",
  "http_address": "127.0.0.1:9600",
  "status": "green",
  "pipeline": {
    "workers": 4,
    "batch_size": 125,
    "batch_delay": 50
  }
}

Задержка или потеря событий

Если рекомендации по сбору и парсингу данных соблюдены, но Data Collector перегружен, а события поступают с задержкой или теряются, проверьте приведенные ниже метрики.

Backpressure

Значение метрики queue_backpressure должно быть близко к нулю. Оно увеличивается, когда Data Collector не справляется с объемом входящих данных и замедляет или приостанавливает их обработку. Возможные причины - ограниченная пропускная способность, высокая нагрузка на процессор или нехватка памяти.

curl -s "http://localhost:9600/_node/stats/flow?pretty"

Пример ответа при исправной работе: queue_backpressure.current близок к нулю:

{
  "flow": {
    "input_throughput": { "current": 1842.3, "lifetime": 1790.5 },
    "filter_throughput": { "current": 1840.1, "lifetime": 1788.9 },
    "output_throughput": { "current": 1839.6, "lifetime": 1788.2 },
    "queue_backpressure": { "current": 0.02, "lifetime": 0.03 },
    "worker_concurrency": { "current": 1.1, "lifetime": 1.0 }
  }
}

Пример при перегрузке: input_throughput остается высоким, output_throughput резко снижается, queue_backpressure приближается к 1, а worker_concurrency - к значению pipeline.workers (все рабочие потоки ожидают записи в output):

{
  "flow": {
    "input_throughput": { "current": 1850.7, "lifetime": 1790.5 },
    "filter_throughput": { "current": 420.3, "lifetime": 1620.1 },
    "output_throughput": { "current": 180.9, "lifetime": 1600.4 },
    "queue_backpressure": { "current": 0.94, "lifetime": 0.41 },
    "worker_concurrency": { "current": 3.98, "lifetime": 2.1 }
  }
}

Что делать

1. Проверьте, не связана ли проблема с Data Storage. Высокое значение queue_backpressure при снижении output_throughput означает, что Data Collector ожидает завершения записи. Проверьте нагрузку на узлы Data Storage. Если причина в Data Storage, устраните ее на этой стороне: увеличение ресурсов Data Collector не поможет

2. Если Data Storage отвечает штатно, а worker_concurrency достиг значения pipeline.workers, увеличьте pipeline.workers или pipeline.batch.size в ${DATA_COLLECTOR_HOME}/config/pipelines.yml (либо в ${DATA_COLLECTOR_HOME}/config/logstash.yml, если настройка общая для всех пайплайнов). Ориентируйтесь на число ядер процессора хоста и не превышайте его. Перезапустите службу

   systemctl restart logstash.service

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

3. Если ограничений в конфигурации нет, проверьте использование ресурсов хоста Data Collector. Для просмотра нагрузки по потокам и определения потока, использующего процессор, выполните команду

   top -H

   Для проверки нагрузки на диск и задержек в течение 5 секунд выполните команду (актуально для очереди persisted; утилита iostat входит в пакет sysstat)

   iostat -x 1 5

   При нехватке ресурсов процессора или памяти проверьте настройки кучи JVM: значения -Xms и -Xmx в ${DATA_COLLECTOR_HOME}/config/jvm.options должны совпадать. При установке Smart Monitor размер кучи по умолчанию составляет половину доступной оперативной памяти хоста (см. Установка параметров Logstash). Если ресурсов по-прежнему не хватает, увеличьте их на сервере или добавьте узел Data Collector

Throughput

Throughput (пропускная способность) показывает объем данных, обрабатываемых Data Collector за единицу времени. Снижение показателя относительно целевого значения может указывать на неподходящую конфигурацию или нехватку ресурсов. Метрика также помогает оценить нагрузку на Data Storage, куда поступают данные из Data Collector. Если доступные ресурсы используются недостаточно, увеличьте pipeline.workers или pipeline.batch.size в конфигурации пайплайна.

curl -s "http://localhost:9600/_node/stats/flow?pretty"
curl -s "http://localhost:9600/_node/stats/pipelines?pretty"

Признак проблемы в ответе _node/stats/pipelines - большое значение queue_push_duration_in_millis относительно duration_in_millis: события долго ожидают в очереди перед обработкой фильтрами и отправкой в output:

{
  "pipelines": {
    "main": {
      "events": {
        "in": 216610,
        "filtered": 148200,
        "out": 148200,
        "duration_in_millis": 365495,
        "queue_push_duration_in_millis": 312466
      }
    }
  }
}

Что делать

См. раздел Backpressure. Высокое значение queue_push_duration_in_millis и низкая пропускная способность обычно указывают на одну причину: выходной плагин не успевает принимать события.

Queue

Очередь Data Collector хранит события, ожидающие обработки. Доступны два типа очередей: memory и persisted. Очередь в оперативной памяти (memory) обеспечивает более быструю обработку, но при сбое или перезапуске службы события могут быть потеряны. Дисковая очередь (persisted) сохраняет события на диск, но может снизить скорость обработки. Выбирайте тип очереди с учетом характеристик потока данных и требований к их сохранности. Убедитесь, что для выбранного типа очереди достаточно оперативной памяти или места на диске.

curl -s "http://localhost:9600/_node/stats/pipelines?pretty"

Пример ответа при исправной работе очереди persisted: queue_size_in_bytes значительно меньше max_queue_size_in_bytes, на диске достаточно свободного места:

{
  "queue": {
    "type": "persisted",
    "capacity": {
      "max_unread_events": 0,
      "page_capacity_in_bytes": 67108864,
      "max_queue_size_in_bytes": 1073741824,
      "queue_size_in_bytes": 3885
    },
    "data": {
      "path": "/app/data/logstash/queue/main",
      "free_space_in_bytes": 936886480896
    },
    "events_count": 12
  }
}

Пример при переполнении: queue_size_in_bytes близок к max_queue_size_in_bytes, свободного места на диске почти не осталось:

{
  "queue": {
    "type": "persisted",
    "capacity": {
      "max_unread_events": 0,
      "page_capacity_in_bytes": 67108864,
      "max_queue_size_in_bytes": 1073741824,
      "queue_size_in_bytes": 1070572288
    },
    "data": {
      "path": "/app/data/logstash/queue/main",
      "free_space_in_bytes": 52428800
    },
    "events_count": 184302
  }
}

В таком состоянии Data Collector прекращает прием новых событий, а в журнале появляются сообщения о заполненной очереди.

к сведению

Для очереди persisted дополнительно проверьте свободное место для директории ${DATA_COLLECTOR_DATA}/queue/<PIPELINE_ID>. При нехватке места пайплайн прекращает прием новых событий.

Что делать

1. Рост очереди обычно является следствием, а не причиной проблемы. Сначала устраните неполадку на стороне output (см. Backpressure и Ошибки передачи данных в Data Storage)
2. Чтобы временно увеличить емкость очереди на время устранения причины, увеличьте лимит параметром queue.max_bytes в ${DATA_COLLECTOR_HOME}/config/pipelines.yml или ${DATA_COLLECTOR_HOME}/config/logstash.yml. Убедитесь, что на диске достаточно места для нового лимита, и перезапустите службу
3. Выберите тип очереди с учетом требований:
   • если потеря событий недопустима, используйте queue.type: persisted
   • если важнее скорость обработки и допустима эпизодическая потеря событий, используйте queue.type: memory

Ошибки конфигурации и запуска пайплайна

Перед запуском пайплайна или после изменения его конфигурации проверьте синтаксис без фактического запуска. Выполняйте проверку от имени пользователя службы (logstash), а не root. Иначе bin/logstash создаст в path.data и path.logs файлы, принадлежащие root, и при следующем запуске службы может возникнуть ошибка доступа:

sudo -u logstash ${DATA_COLLECTOR_HOME}/bin/logstash --config.test_and_exit -f <PIPELINE_FILE> --path.settings ${DATA_COLLECTOR_HOME}/config

Если служба Data Collector не запускается или постоянно перезапускается, проверьте:

• состояние службы

  systemctl status logstash.service

  Пример при сбое: служба постоянно перезапускается

  ● logstash.service - logstash
     Loaded: loaded (/etc/systemd/system/logstash.service; enabled; vendor preset: disabled)
     Active: activating (auto-restart) (Result: exit-code) since Tue 2026-10-07 11:05:02 UTC; 3s ago
    Process: 20911 ExecStart=/app/logstash/bin/logstash (code=exited, status=1/FAILURE)

• основной журнал службы

  tail -n 100 ${DATA_COLLECTOR_LOGS}/logstash-plain.log

  Пример записи об ошибке конфигурации в журнале

  [2026-10-26T12:07:20,575][ERROR][logstash.agent           ] Failed to execute action {:action=>LogStash::PipelineAction::Create/pipeline_id:test_config_error, :exception=>"LogStash::ConfigurationError", :message=>"Expected one of '\\\"', any character, '\"' at line 17, column 1 (byte 169) after filter {\nmutate {\n  add_field => { \"test\" => \"test }\n}\n}\n\noutput {\n    stdout {}\n}\n", :backtrace=>["/app/logstash/logstash-core/lib/logstash/compiler.rb:32:in `compile_imperative'", "..."]}

Одна из распространенных причин сбоя службы - отсутствие настроенных пайплайнов в директории ${DATA_COLLECTOR_HOME}/config/conf.d (см. Создание типового пайплайна).

Еще одна распространенная причина - неверные права доступа к файлам и директориям службы, например после изменения конфигурации от имени другого пользователя или восстановления из резервной копии. Служба Data Collector работает от имени пользователя logstash и должна иметь права на запись в следующие директории:

• ${DATA_COLLECTOR_HOME}/config/conf.d - файлы пайплайнов
• ${DATA_COLLECTOR_LOGS} - файлы журналов
• ${DATA_COLLECTOR_DATA} - очередь, Dead Letter Queue, sincedb

Пример ошибки доступа в журнале (для конфигурации, журналов и path.data различается только путь в rb_sysopen):

[FATAL][logstash.runner] An unexpected error occurred! {:error=>#<Errno::EACCES: Permission denied @ rb_sysopen - /app/data/logstash/queue/main/checkpoint.head>, ...}

Проверьте права доступа командой:

ls -la ${DATA_COLLECTOR_HOME}/config/conf.d ${DATA_COLLECTOR_LOGS} ${DATA_COLLECTOR_DATA}

Что делать

1. Исправьте конфигурацию по тексту ошибки из --config.test_and_exit или журнала (в примере - синтаксическая ошибка в строке 17)

2. Если пайплайнов нет, создайте их по инструкции Создание типового пайплайна

3. Если причина в правах доступа, рекурсивно назначьте владельцем трех директорий logstash:logstash либо пользователя и группу, от имени которых работает служба

   chown -R logstash:logstash ${DATA_COLLECTOR_HOME}/config/conf.d ${DATA_COLLECTOR_LOGS} ${DATA_COLLECTOR_DATA}

4. Перезапустите службу и убедитесь, что она остается в состоянии active (running)

   systemctl restart logstash.service
   systemctl status logstash.service

Dead Letter Queue

Dead Letter Queue (DLQ) сохраняет события, которые не удалось записать через output, например из-за конфликта маппинга в Data Storage. DLQ включается параметром dead_letter_queue.enable: true в ${DATA_COLLECTOR_HOME}/config/pipelines.yml. События сохраняются в директории:

${DATA_COLLECTOR_DATA}/dead_letter_queue/<PIPELINE_ID>/

Рост объема данных в этой директории указывает на регулярные ошибки записи в Data Storage: несоответствие маппинга, превышение лимитов индекса или недоступность Data Storage. Параметр dead_letter_queue.max_bytes ограничивает размер DLQ. После достижения лимита новые события отбрасываются без записи.

Что делать

1. Просмотрите содержимое DLQ с помощью вспомогательного пайплайна, чтобы определить исходные события и причину отказа. Для кодека rubydebug требуется опция metadata => true: без нее поле @metadata с причиной ошибки не появится в выводе. Причина находится в [@metadata][dead_letter_queue][reason]

   input {
     dead_letter_queue {
       path => "/app/data/logstash/dead_letter_queue/<PIPELINE_ID>"
     }
   }
   output {
     stdout { codec => rubydebug { metadata => true } }
   }

2. Устраните причину отказа

   • при конфликте типа поля в маппинге скорректируйте маппинг индекса или преобразуйте тип поля в блоке filter перед отправкой в output (см. Общие рекомендации по сбору данных)
   • если Data Storage недоступен, см. Ошибки передачи данных в Data Storage

3. После устранения причины при необходимости повторно отправьте события из DLQ, указав в output вспомогательного пайплайна целевой индекс Data Storage вместо stdout

4. Если накопленные события больше не нужны, очистите DLQ одним из двух способов

   • остановите пайплайн и вручную удалите содержимое его директории DLQ: автоматически оно не удаляется
   • не останавливая пайплайн, включите во вспомогательном пайплайне опцию clean_consumed => true для плагина dead_letter_queue в блоке input: она удаляет прочитанные сегментные файлы, не затрагивая файлы, которые пайплайн может читать в этот момент

Ошибки передачи данных в Data Storage

Если данные не поступают в Data Storage, проверьте журнал ${DATA_COLLECTOR_LOGS}/logstash-plain.log. Все пайплайны записывают сообщения в один файл; записи содержат pipeline_id. При нескольких пайплайнах отфильтруйте сообщения по нужному pipeline_id, чтобы определить источник ошибки:

grep 'pipeline_id:main' ${DATA_COLLECTOR_LOGS}/logstash-plain.log

Проверьте не только предупреждения о повторных попытках подключения (retrying), но и ошибки соединения. Их содержание зависит от причины:

[WARN][logstash.outputs.opensearch] Attempted to resurrect connection to dead OpenSearch instance, but got an error {:url=>"https://192.0.2.10:9200/", :exception=>Manticore::ConnectTimeout, :message=>"connect timed out after 5000 milliseconds"}

[ERROR][logstash.outputs.opensearch] Failed to install template {:message=>"PUT https://192.0.2.10:9200/_template/... failed: [401] {\"error\":\"unauthorized\"}"}

[ERROR][logstash.outputs.opensearch] SSL Exception {:message=>"javax.net.ssl.SSLHandshakeException: PKIX path building failed: unable to find valid certification path to requested target"}

Типичные причины и действия:

• недоступность хоста или порта Data Storage в блоке output пайплайна (признак - ConnectTimeout или Connection refused) - проверьте сетевое соединение командой curl -v https://<data_storage_host>:9200 и соответствие адреса в output фактическому адресу Data Storage
• неверные учетные данные для подключения к Data Storage (признак - ошибка 401 или 403 в журнале) - проверьте имя пользователя, пароль или ключ API, заданные в блоке output пайплайна
• ошибка проверки сертификата при использовании TLS (признаки - SSLHandshakeException и PKIX path building failed) - проверьте цепочку сертификатов командой curl -v --cacert <путь до сертификата ЦС> https://<data_storage_host>:9200 без отключения проверки, замените сертификат по инструкции Замена старых сертификатов и перезапустите службу
• Data Storage не успевает принимать данные (растет число rejected в пуле потоков или срабатывает circuit breaker) - устраните причину на стороне Data Storage (см. Диагностика проблем Data Storage). Увеличение таймаутов или числа повторных попыток на Data Collector лишь скрывает проблему

После устранения причины убедитесь, что предупреждения retrying больше не появляются в журнале, а объем данных в очереди и DLQ снижается.

Полезные ссылки

• общие рекомендации по сбору данных
• создание типового пайплайна
• мониторинг системы
• диагностика проблем Data Storage