LogsQL — язык запросов к логам

Язык запросов LogsQL для поиска и анализа лог-записей в Proto Observability Platform.
Tags:

Обзор

LogsQL — простой, но мощный язык запросов к логам в Proto Observability Platform. Он предоставляет следующие возможности:

  • Полнотекстовый поиск по любому полю лог-записи. По умолчанию поиск выполняется по полю _msg.
  • Фильтры различных типов: поиск по слову (word), по фразе (phrase), по префиксу (prefix) и другие.
  • Комбинирование фильтров в сложные логические выражения с помощью операторов AND, OR и NOT.
  • Извлечение структурированных полей из неструктурированных лог-записей непосредственно во время выполнения запроса.
  • Вычисление статистики по выбранным лог-записям с использованием встроенных статистических функций.

LogsQL оптимизирован для быстрого выполнения запросов над большими объёмами лог-данных и поддерживает инкрементальный анализ результатов с помощью механизма пайпов.

Введение в LogsQL

В этом разделе приводится пошаговое руководство по основам работы с языком запросов LogsQL. Все примеры можно выполнять в интерфейсе обозревателя логов Proto Observability Platform или через CLI для работы с логами.

Простейший запрос — поиск по слову

Самый простой запрос LogsQL — это одно слово. Платформа выполнит полнотекстовый поиск по полю _msg всех лог-записей:

error

Этот запрос вернёт все лог-записи, содержащие слово error в поле _msg.

Фильтрация по времени

При работе с большими объёмами логов рекомендуется всегда указывать временной интервал. Это значительно повышает производительность запроса:

_time:5m error

Данный запрос вернёт лог-записи со словом error, созданные за последние 5 минут. Поддерживаются различные единицы измерения: s (секунды), m (минуты), h (часы), d (дни), w (недели).

Можно также задать абсолютный временной диапазон:

_time:[2024-01-01, 2024-01-02)

Неявный оператор AND

Несколько фильтров, разделённых пробелом, объединяются оператором AND по умолчанию. Следующие два запроса эквивалентны:

_time:5m error

error AND _time:5m

Порядок фильтров не имеет значения — платформа самостоятельно определяет оптимальный порядок выполнения.

Сортировка и ограничение результатов

Для сортировки результатов используется пайп sort, а для ограничения количества — limit:

_time:5m error | sort by (_time) desc | limit 10

Этот запрос вернёт 10 последних лог-записей со словом error за последние 5 минут, отсортированных по времени в порядке убывания.

Выбор конкретных полей

Пайп fields позволяет выбрать только нужные поля в результатах:

error _time:5m | fields _time, _stream, _msg

Результат будет содержать только три поля: время записи, поток и текст сообщения.

Исключение с помощью NOT

Оператор NOT (или его сокращённая форма -) позволяет исключить лог-записи, соответствующие определённому условию:

_time:5m error -buggy_app

Этот запрос эквивалентен:

_time:5m error NOT buggy_app

Обе формы вернут лог-записи со словом error, но исключат те, которые содержат слово buggy_app.

Поиск по конкретному полю

По умолчанию текстовый поиск выполняется по полю _msg. Чтобы искать по другому полю, укажите его имя перед двоеточием:

_time:5m log.level:error

Этот запрос найдёт записи, в которых поле log.level содержит значение error.

Можно комбинировать поиск по нескольким полям:

_time:5m log.level:error host:server-01

Фильтрация по потокам для повышения производительности

Фильтр по потокам (_stream) — один из самых эффективных способов сузить область поиска. Фильтр потоков заключается в фигурные скобки:

_time:5m log.level:error {app="my_service"}

Поддерживаются операторы сравнения, включая =, !=, =~ (регулярное выражение) и !~ (отрицание регулярного выражения):

_time:5m log.level:error {app!~"buggy_app|foobar"}

Этот запрос найдёт записи уровня error, исключив потоки приложений buggy_app и foobar. Фильтрация по потокам существенно ускоряет выполнение запросов, так как позволяет платформе пропустить нерелевантные данные на самом раннем этапе.

Вычисление статистики

Пайп stats позволяет вычислять агрегированные метрики по выбранным лог-записям:

_time:5m error | stats count() logs_with_error

Этот запрос подсчитает количество лог-записей со словом error за последние 5 минут и вернёт результат с именем logs_with_error.

Можно группировать статистику по полям:

_time:5m error | stats by (host) count() errors_per_host

А также вычислять несколько функций одновременно:

_time:5m error | stats count() total, count_uniq(host) unique_hosts

Использование оператора OR

Для объединения условий по логическому ИЛИ используется оператор OR:

_time:5m error OR warning

Этот запрос вернёт записи, содержащие слово error или слово warning (или оба). Оператор AND имеет более высокий приоритет, чем OR. Для явного управления приоритетом используйте круглые скобки:

_time:5m (error OR warning) host:server-01

Поиск по фразе

Для поиска точной последовательности слов заключите фразу в двойные кавычки:

_time:5m "connection refused"

Этот запрос найдёт лог-записи, содержащие именно фразу connection refused, а не просто оба слова по отдельности.

Поиск по префиксу

Для поиска слов, начинающихся с определённого префикса, добавьте символ * в конце:

_time:5m err*

Запрос вернёт записи, содержащие слова, начинающиеся с err: error, errors, erroneous и т. д.

Ключевые концепции

Слово (Word)

LogsQL рассматривает значения полей лог-записей как последовательности слов, разделённых несловесными символами. К несловесным символам относятся: пробелы, скобки, знаки пунктуации, кавычки и другие специальные символы.

Пример: строка foo: (bar,"тест")! разбивается на три слова: foo, bar и тест.

Слова могут содержать любые символы UTF-8, включая кириллицу и другие национальные алфавиты. Это позволяет эффективно искать по логам, содержащим текст на разных языках.

При поиске по слову LogsQL ищет точное вхождение слова, а не подстроку. Например, запрос error не найдёт слово errors. Для поиска по подстроке используйте поиск по префиксу (error*) или фильтр подстроки.

Синтаксис запросов

Запрос LogsQL состоит из двух частей:

  1. Фильтры — определяют, какие лог-записи будут выбраны. Запрос должен содержать хотя бы один фильтр.
  2. Пайпы (необязательно) — обрабатывают и трансформируют результаты фильтрации. Указываются после символа |.

Общий формат запроса:

<фильтры> | <пайп1> | <пайп2> | ...

Пример:

_time:5m error | stats count() errors

В этом запросе _time:5m error — это фильтры (временной фильтр и поиск слова), а stats count() errors — пайп для вычисления статистики.

Типы фильтров

LogsQL поддерживает широкий набор фильтров:

  • Текстовые фильтры: поиск по слову, фразе, префиксу, подстроке, регулярному выражению.
  • Временные фильтры: _time для ограничения диапазона по времени.
  • Фильтры потоков: {...} для выбора конкретных потоков логов.
  • Числовые фильтры: диапазоны значений числовых полей.
  • Логические операторы: AND, OR, NOT для комбинирования фильтров.

Полный перечень фильтров описан в справочнике фильтров.

Системные поля

Хранилище логов автоматически добавляет к каждой лог-записи следующие системные поля:

  • _msg — текст лог-сообщения. Поле по умолчанию для полнотекстового поиска.
  • _time — временная метка лог-записи.
  • _stream — идентификатор потока логов, определяющий набор меток, по которым логи группируются.

Эти поля доступны для фильтрации и выбора в любом запросе LogsQL.

Модель данных

Каждая лог-запись в хранилище представляет собой набор полей (пар «ключ-значение»). Поля делятся на системные (_msg, _time, _stream) и пользовательские, которые добавляются при отправке лог-записей. Пользовательские поля могут содержать произвольные строковые и числовые значения.

Поле сообщения

Поле _msg содержит текст лог-сообщения. По умолчанию все текстовые фильтры применяются к этому полю. Чтобы применить фильтр к другому полю, укажите имя поля перед фильтром через двоеточие, например: log.level:error.

Поле времени

Поле _time содержит временную метку лог-записи в формате RFC3339 (https://www.rfc-editor.org/rfc/rfc3339). Используется для фильтрации по временным диапазонам с помощью фильтра по времени.

Поля потока

Поля потока (_stream) определяют набор меток, по которым лог-записи группируются в потоки. Потоки позволяют эффективно фильтровать логи по источнику, например по приложению, хосту или окружению. Для фильтрации по потокам используется фильтр потока.

Дополнительные разделы

Подробная документация по отдельным аспектам LogsQL доступна на следующих страницах:

  • Фильтры LogsQL — полный справочник фильтров: текстовые, временные, числовые, логические и специальные фильтры.
  • Пайпы LogsQL — обработка и трансформация результатов запросов: сортировка, выбор полей, извлечение данных, форматирование.
  • Функции статистики — статистические функции для агрегирования данных: подсчёт, уникальные значения, суммы, средние и другие.
  • Справочник — литералы, рекомендации по производительности, устранение неполадок.