Загрузка логов JSON и TXT

Материал из Документация Ключ-АСТРОМ

Загрузка логов JSON и TXT

API загрузки логов принимает логи в форматах JSON, TXT и OTLP. На этой странице описаны форматы JSON и текстовый. Документацию по OTLP см. в разделе Форматы OTLP. API загрузки логов отвечает за сбор данных и их пакетную пересылку в Ключ-АСТРОМ.

Подробности о поддерживаемых полезных нагрузках, аутентификации, параметрах и объектах тела запроса см. в разделе Log Monitoring API v2 — POST ingest logs. Подробности об ограничениях см. в разделе Ограничения по умолчанию для управления логами и аналитики.

Преобразование данных и автоматический разбор JSON

API загрузки логов собирает и пытается автоматически преобразовать данные логов. Каждая запись лога из загруженного пакета сопоставляется с одной записью лога Ключ-АСТРОМ, которая содержит три специальных атрибута: timestamp, loglevel, content, а также атрибуты «ключ-значение». Эти четыре свойства устанавливаются на основе ключей, присутствующих во входном объекте JSON, следующим образом.

Временная метка

timestamp устанавливается на основе значения первого найденного ключа из следующего списка, проверяемого в указанном порядке (без учёта регистра): timestamp, @timestamp, _timestamp, eventtime, date, published_date, syslog.timestamp, time, epochSecond, startTime, datetime, ts, timeMillis, @t. Поддерживаются форматы: время Unix epoch в UTC, RFC3339 и RFC3164. Время Unix epoch может быть представлено в секундах, миллисекундах и, начиная с версии Ключ-АСТРОМ 1.339+, в дробных секундах. Для неподдерживаемых форматов временных меток используется текущая временная метка, а значение неподдерживаемого формата сохраняется в атрибуте unparsed_timestamp. Записи логов старше предельного возраста логов отбрасываются. Временные метки, опережающие текущее время более чем на 10 минут, заменяются текущим временем. Если в записи лога нет поддерживаемого ключа временной метки, значением по умолчанию является текущая временная метка. Если в временной метке нет часового пояса, часовым поясом по умолчанию является UTC.

Уровень логирования

loglevel устанавливается на основе значения первого найденного ключа из следующего списка, проверяемого в указанном порядке (без учёта регистра): loglevel, status, severity, level, syslog.severity. Значение по умолчанию — NONE.

Содержимое

content устанавливается на основе значения первого найденного ключа из следующего списка, проверяемого в указанном порядке (без учёта регистра): content, message, payload, body, log, _raw (поддерживается только в модели данных raw). Значение и обработка по умолчанию зависят от модели данных, используемой для обработки входных данных.

Атрибуты

Атрибуты логов содержат все остальные ключи из входного объекта JSON, кроме тех, что используются для timestamp, loglevel и content. Атрибуты первого уровня предпочтительно должны сопоставляться с семантическими атрибутами, чтобы Ключ-АСТРОМ мог связать их с контекстом. Все атрибуты можно использовать в запросах, хотя Семантический словарь помогает ИИ Ключ-АСТРОМ в интерпретации логов. Подробнее см. Семантический словарь.

Автоматический атрибут. Атрибут dt.auth.origin автоматически добавляется к каждой записи лога, загруженной через API. Этот атрибут представляет собой публичную часть API-ключа, который источник логов авторизует для подключения к API общей загрузки логов.

Обработка атрибутов различается в зависимости от типа тенанта и среды:

  • Логи с OpenPipeline и пользовательской обработкой (SaaS-версия Ключ-АСТРОМ 1.295+, версия АктивногоШлюза среды 1.295+): поддерживаются богатые типы данных, что позволяет использовать разнообразные атрибуты в запросах. Ключи чувствительны к регистру.
  • Логи с OpenPipeline, направленные в Classic Pipeline: все ключи атрибутов приводятся к нижнему регистру, а все значения атрибутов преобразуются в строки. Все атрибуты можно использовать в запросах.

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

Существует две модели данных, которые определяют, как структурированные логи обрабатываются конечными точками загрузки логов: raw и flattened. Разница между ними заключается в способе преобразования атрибутов со значениями-объектами. Если эта опция конфигурации не указана, поведение по умолчанию зависит от того, когда была создана ваша среда.

  • Для версии Ключ-АСТРОМ 1.331+: Raw.
  • Для версий Ключ-АСТРОМ 1.330 и более ранних: Flattened.

Экранирование в примерах вывода предназначено только для визуализации.

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

Модель данных raw сохраняет исходную структуру и контекст лога, поддерживая целостность данных. Это обеспечивает простое взаимодействие и запросы, поскольку представление записи лога в Ключ-АСТРОМ остаётся таким же, как в источнике. Рекомендуется использовать этот подход для сильно вложенных JSON-логов, так как он сохраняет семантическое значение и взаимосвязи между точками данных. При использовании средств доставки логов, таких как Fluentbit, Fluentd или Logstash, избегайте использования JSON-парсеров на стороне средства доставки и позвольте Ключ-АСТРОМ выполнить разбор JSON. Этот подход снижает нагрузку на обработку на вашем средстве доставки логов и обеспечивает согласованное поведение при разборе.

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

Атрибуты с непримитивными типами

Атрибуты типа «объект» сохраняются как строки JSON. Последующие этапы загрузки Ключ-АСТРОМ (OpenPipeline, приложение «Логи») поддерживают этот формат для удобной обработки и анализа логов. Типы «массив» сохраняются как массивы, но содержащиеся в них типы унифицируются к одному типу. Сложные значения (такие как массивы или объекты) сопоставляются со строковыми значениями JSON. Если какое-либо значение в массиве является строкой или если какое-либо значение должно быть преобразовано в строку (например, объект или массив), целевым типом всего массива становится строка. Если все значения в исходном массиве являются числовыми, целевым типом массива становится числовой. Нулевые значения считаются совместимыми с любым типом.

Пример:

Вход:
{
  "content": "Transaction successfully processed.",
  "transaction": { "id": "TXN12345", "amount": 250.75 },
  "auditTrail": [ "Created", "Approved", 3 ]
}

Выход:
{
  "content": "Transaction successfully processed.",
  "transaction": "{\"id\": \"TXN12345\", \"amount\": 250.75}",
  "auditTrail": ["Created", "Approved", "3"]
}

Поведение, связанное с содержимым

Правила ниже определяют, как выбирается и формируется поле content.

Поддерживаемый атрибут содержимого не найден

Если ни один из поддерживаемых атрибутов содержимого не найден, в качестве поля content выходной записи лога устанавливается всё JSON-представление события лога. Исходный JSON сохраняется как есть. Поле _raw не входит в число поддерживаемых полей содержимого для этой модели данных.

Пример:

Вход:
{ "transaction": { "id": "TXN12345", "amount": 250.75 }}

Выход:
{
  "content": "{\"transaction\":{\"id\":\"TXN12345\",\"amount\":250.75}}",
  "transaction": { "id": "TXN12345", "amount": 250.75 }
}
Сложные значения в поддерживаемых атрибутах содержимого

Любой атрибут, являющийся объектом, включая content, рассматривается как стандартный атрибут.

Пример:

Вход:
{
  "payload": "This will be used for content.",
  "message": { "id": "TXN12345", "amount": 250.75 }
}

Выход:
{
  "content": "This will be used for content.",
  "message.id": "TXN12345",
  "message.amount": 250.75
}

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

Модель данных flattened обеспечивает прямой доступ к значениям атрибутов через простые ключевые пути. Этот подход предоставлен для совместимости. Он также может подходить для определённых вариантов использования, например, когда все вложенные значения JSON должны быть доступны на корневом уровне.

Атрибуты с непримитивными типами

В модели данных flattened вложенные объекты в атрибутах логов преобразуются в плоские пары значений. Когда атрибут лога содержит объект, каждое вложенное свойство становится отдельным атрибутом. Этот процесс работает для атрибутов до пятого уровня, атрибуты глубже этого уровня пропускаются. Типы «массив» сохраняются как массивы, но содержащиеся в них типы унифицируются к одному типу. Сложные значения (такие как массивы или объекты) сопоставляются со строковыми значениями JSON. Если какое-либо значение в массиве является строкой или если какое-либо значение должно быть преобразовано в строку (например, объект или массив), целевым типом всего массива становится строка. Если все значения в исходном массиве являются числовыми, целевым типом массива становится числовой. Нулевые значения считаются совместимыми с любым типом.

Пример:

Вход:
{
  "content": "Transaction successfully processed.",
  "transaction": { "id": "TXN12345", "amount": 250.75 },
  "auditTrail": [ "Created", "Approved", 3 ]
}

Выход:
{
  "content": "Transaction successfully processed.",
  "transaction.id": "TXN12345",
  "transaction.amount": 250.75,
  "auditTrail": ["Created", "Approved", "3"]
}
Конфликты имён

Когда атрибуты сохраняются в плоском виде на стороне Ключ-АСТРОМ, могут возникать конфликты имён, если атрибуты на разных уровнях имеют одинаковое имя. Ключ-АСТРОМ обрабатывает эти конфликты, добавляя префиксы к перезаписанным атрибутам.

Пример:

Вход:
{ "service": { "instance": { "id": "abc" }}, "service.instance": { "id": "xyz" }}

Выход:
{
  "service.instance.id": "abc",
  "overwritten1.service.instance.id": "xyz"
}

Обработка атрибутов API загрузки логов

API загрузки логов дополнительно принимает атрибуты логов через:

  • Параметры запроса
  • Специальный заголовок X-Astromkey-Attr

Эти атрибуты объединяются с теми, что предоставлены в теле записи лога, в соответствии с правилами, описанными ниже.

Атрибуты параметров запроса

  • Все параметры запроса, переданные в конечную точку API загрузки логов, добавляются к атрибутам тела записи лога.
  • Если ключ параметра появляется несколько раз, все значения записываются как атрибут-массив.
  • Ключи и значения подчиняются тем же правилам разбора атрибутов, что и атрибуты тела.
  • Некоторые параметры обрабатываются API для внутренних целей и никогда не появляются в качестве атрибутов записи лога, даже если указаны явно (например, используемые в заголовке X-Astromkey-Options).

Пример:

Запрос:
POST /api/v2/logs/ingest?env=prod&env=blue&team=payments
{ "content": "Transaction successfully processed."}

Результирующие атрибуты:
{
  "content": "Transaction successfully processed.",
  "env": ["prod", "blue"],
  "team": "payments"
}

Атрибуты на основе заголовков (X-Astromkey-Attr)

API поддерживает специальный заголовок для передачи дополнительных атрибутов:

X-Astromkey-Attr: region=eu-central-1&team=core

Правила:

  • Ключи и значения подчиняются тем же правилам разбора атрибутов, что и параметры запроса.
  • Поведение с несколькими значениями также поддерживается внутри атрибутов заголовка.
  • Применяются те же ограничения на зарезервированные имена параметров.

Правила приоритета атрибутов

Когда атрибуты появляются в нескольких местах, API загрузки логов применяет приоритет атрибутов, сохраняя при этом значения тела для аудита. Атрибуты применяются в следующем порядке:

  1. Параметры запроса (наивысший приоритет)
  2. Заголовок X-Astromkey-Attr
  3. Тело записи лога (наименьший приоритет; существующий путь загрузки)

Поведение при переопределении

Когда атрибуты из параметров запроса или заголовка переопределяют атрибуты тела:

  • Итоговое значение атрибута устанавливается в соответствии с правилами приоритета источников атрибутов.
  • Значения, уже присутствовавшие в теле лога, сохраняются и зеркалируются под ключами overwrittenN.<ключ_атрибута>, где N — увеличивающееся целое число (1, 2, …), в зависимости от того, сколько значений из тела пришлось сохранить. Это обеспечивает уникальность даже при множественных конфликтах.
  • Только значения, происходящие из тела лога, сохраняются под ключами overwrittenN.*. Атрибуты, переопределённые источниками с более высоким приоритетом, не создают перезаписанных копий.

Пример:

Запрос:
POST /api/v2/logs/ingest?team=frontend
Body: { "content": "Transaction successfully processed.", "team": "backend"}

Результирующие атрибуты:
{
  "content": "Transaction successfully processed.",
  "team": "frontend",
  "overwritten1.team": "backend"
}

Поведение при тарификации

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

Источник — https://doc.ruscomtech.ru/index.php?title=Загрузка_логов_JSON_и_TXT&oldid=7010