API мониторинг логов - POST прием логов

Материал из Документация Ключ-АСТРОМ
Версия от 17:52, 9 сентября 2025; IKuznetsov (обсуждение | вклад) (Новая страница: «Отправляет пользовательские логи в Ключ-АСТРОМ. Эта конечная точка доступна в вашей '''Saa...»)
(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)

Отправляет пользовательские логи в Ключ-АСТРОМ.

Эта конечная точка доступна в вашей SaaS-среде, или, в качестве альтернативы, вы можете разместить её на устройстве Environmental АктивномШлюзе с включённым модулем сбора данных Log Analytics . Этот модуль по умолчанию включён на всех ваших устройствах АктивногоШлюза.

Запрос использует один из следующих типов полезной нагрузки:

  • text/plain—ограничено одним событием логов.
  • application/json, application/jsonl, application/jsonlines, application/jsonlines+json, application/x-ndjson, application/x-jsonlines—поддержка нескольких событий логов в одной полезной нагрузке.

Обязательно установите правильный заголовок Content-Type и закодируйте полезную нагрузку с помощью UTF-8 , например: application/json; charset=utf-8.

POST SaaS https://{your-environment-id}.live.astromkey.com/api/v2/logs/ingest
Environment АктивныйШлюз

Cluster АктивныйШлюз

https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/logs/ingest

Аутентификация

Для выполнения этого запроса вам понадобится токен доступа с областью действия logs.ingest.

Чтобы узнать, как его получить и использовать, см. раздел Токены и аутентификация.

Параметры

При использовании обработки логов с помощью пользовательского конвейера обработки (OpenPipeline) функция Ingest поддерживает все типы данных JSON для значений атрибутов. Для этого требуется SaaS-версия 1.295+ при использовании конечной точки SaaS API или АктивныйШлюз версии 1.295+ при использовании конечной точки API АктивныйШлюз. Во всех остальных случаях все полученные значения преобразуются в строковый тип.
Параметр Тип Описание Относится к Необходимость
content-type string Позволяет указать тип контента с помощью параметра запроса. Имеет приоритет над значением, указанным в заголовке Content-Type. запросу необязательный
body LogMessageJson Тело запроса. Содержит одно или несколько событий логов для обработки.

Конечная точка принимает один из следующих типов полезной нагрузки, определенных заголовком Accept :

  • text/plain: поддерживает только одно событие логов.
  • application/json: поддерживает несколько событий логов в одном массиве JSON.
  • application/jsonl, application/jsonlines, application/x-ndjson, или application/x-jsonlines: поддерживает несколько событий логов в качестве полезной нагрузки строк JSON (один объект JSON на строку).
 телу необязательный

Объекты тела запроса

Объект LogMessageJson​

Сообщение логов в формате JSON. Используйте один объект, представляющий одно событие, или массив объектов, представляющих несколько событий.

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

  • Временная метка:
    • Самая ранняя временная метка для события логов — это текущее время минус 24 часа. Если событие логов содержит временную метку, более раннюю, чем текущее время минус 24 часа, событие удаляется.
    • Временная метка события логов не ограничивается будущим временем. Если событие логов содержит временную метку, отстоящую более чем на 10 минут вперёд, временная метка события будет перезаписана текущим временем на сервере.
    • Поддерживаются следующие форматы: миллисекунды UTC, RFC3339 и RFC3164. Для отсутствующей метки времени используется текущая метка времени. Для неподдерживаемого формата метки времени используется текущая метка времени, а значение неподдерживаемого формата сохраняется в атрибуте unparsed_timestamp (в Log Monitoring Classic этот атрибут не индексируется).
  • Уровень серьёзности. Если не задан, используется NONE.
  • Содержимое. Если ключ содержимого не задан или содержит JSON-объект, поле содержимого заполняется строковым представлением всего принятого JSON-объекта.
  • Атрибуты:
    • Логи в Grail с обработкой OpenPipeline (Ключ-АСТРОМ SaaS версии 1.295+, Environment АктивныйШлюз версии 1.295+): поддерживаются все типы данных JSON (строка, число, логическое значение, null). Все атрибуты индексируются и могут использоваться в запросах. Ключи чувствительны к регистру.
    • Логи Grail без пользовательской обработки OpenPipeline: поддерживаются только значения указанного типа string. Все атрибуты индексируются и могут использоваться в запросах. Ключи регистронезависимы (в нижнем регистре).
    • Log Monitoring Classic: поддерживаются только значения указанного типа string. Семантические атрибуты индексируются и могут использоваться в запросах. Неподдерживаемый ключ не индексируется и не может использоваться в индексировании и агрегации. Ключи регистронезависимы (в нижнем регистре).
  • Семантические атрибуты отображаются в агрегациях (фасетах) в средстве просмотра логов и событий. Подробнее см. на странице документации по семантическому словарю.
  • Автоматический атрибут. Атрибут dt.auth.origin автоматически добавляется к каждой записи логов, полученной через API. Этот атрибут представляет собой открытую часть ключа API, которую источник логов разрешает использовать для подключения к универсальному API получения логов.

Структура атрибутов

Сложные объекты сводятся к плоским, что облегчает работу с ними и упрощает их представление. Ниже приведены рекомендации по процессу:

  1. Ключи объединяются с помощью точки (.) до тех пор, пока в иерархии не будет достигнуто простое значение. Например:
    Базовый JSON:
    {"test": { "attribute": {"one": "value 1", "two": "value 2"}}}
    Результат:
    {"test.attribute.one": "value 1", "test.attribute.two": "value 2" }
  2. При обнаружении массива на этом уровне создаётся многозначный атрибут. Если в массиве есть непростые значения, сохраняется строковое значение JSON.
  3. Конфликты имен разрешаются следующим образом:
    • В случае конфликта имён, когда ключ перезаписывается, к нему добавляется префикс «overwritten». Например:
      Базовый JSON:
      {"host.name": "abc", "host": { "name": "xyz"}}
      Результат:
      {"host.name": "abc", "overwritten1.host.name": "xyz"}
    • При возникновении второго конфликта добавляется индекс, начинающийся с 1:
      Базовый JSON:
      {"service.instance.id": "abc", "service": { "instance.id": "xyz", "instance": { "id": "123"}}}
      Результат:
      {"service.instance.id": "abc", "overwritten1.service.instance.id": "xyz", "overwritten2.service.instance.id": "123" }
  4. Атрибуты могут иметь максимальный уровень вложенности 5. Атрибуты, вложенность которых превышает этот уровень, удаляются. Код ответа — 200, и возвращается сообщение «Event(s) has attributes which are too nested for records:» со списком ограниченного количества индексов записей.

Ограничения

Пожалуйста, обратитесь к следующим страницам документации:

Поддерживаемые ключи временных меток:

  • @timestamp
  • _timestamp
  • date
  • eventtime
  • published_date
  • syslog.timestamp
  • timestamp

Поддерживаемые ключи контента:

  • body
  • content
  • log
  • message
  • payload

Поддерживаемые ключи серьезности:

  • audit.action
  • audit.identity
  • audit.result
  • aws.account.id
  • aws.arn
  • aws.log_group
  • aws.log_stream
  • aws.region
  • aws.resource.id
  • aws.resource.type
  • aws.service
  • azure.location
  • azure.resource.group
  • azure.resource.id
  • azure.resource.name
  • azure.resource.type
  • azure.subscription
  • cloud.account.id
  • cloud.availability_zone
  • cloud.provider
  • cloud.region
  • container.image.name
  • container.image.tag
  • container.name
  • db.cassandra.keyspace
  • db.connection_string
  • db.hbase.namespace
  • db.jdbc.driver_classname
  • db.mongodb.collection
  • db.mssql.instance_name
  • db.name
  • db.operation
  • db.redis.database_index
  • db.statement
  • db.system
  • db.user
  • device.address
  • dt.active_gate.group.name
  • dt.active_gate.id
  • dt.code.filepath
  • dt.code.func
  • dt.code.lineno
  • dt.code.ns
  • dt.ctg.calltype
  • dt.ctg.extendmode
  • dt.ctg.gatewayurl
  • dt.ctg.program
  • dt.ctg.rc
  • dt.ctg.requesttype
  • dt.ctg.serverid
  • dt.ctg.termid
  • dt.ctg.transid
  • dt.ctg.userid
  • dt.entity.cloud_application
  • dt.entity.cloud_application_instance
  • dt.entity.cloud_application_namespace
  • dt.entity.container_group
  • dt.entity.container_group_instance
  • dt.entity.custom_device
  • dt.entity.host
  • dt.entity.host_group
  • dt.entity.kubernetes_cluster
  • dt.entity.kubernetes_node
  • dt.entity.process_group
  • dt.entity.process_group_instance
  • dt.entity.service
  • dt.event.group_label
  • dt.event.key
  • dt.events.root_cause_relevant
  • dt.exception.messages
  • dt.exception.serialized_stacktraces
  • dt.exception.types
  • dt.extension.config.id
  • dt.extension.ds
  • dt.extension.name
  • dt.extension.status
  • dt.host.ip
  • dt.host.smfid
  • dt.host.snaid
  • dt.host_group.id
  • dt.http.application_id
  • dt.http.context_root
  • dt.ingest.debug_messages
  • dt.ingest.warnings
  • dt.kubernetes.cluster.id
  • dt.kubernetes.cluster.name
  • dt.kubernetes.config.id
  • dt.kubernetes.event.involved_object.kind
  • dt.kubernetes.event.involved_object.name
  • dt.kubernetes.event.reason
  • dt.kubernetes.node.name
  • dt.kubernetes.node.system_uuid
  • dt.kubernetes.topmost_controller.kind
  • dt.kubernetes.workload.kind
  • dt.kubernetes.workload.name
  • dt.network_zone.id
  • dt.os.description
  • dt.os.type
  • dt.process.commandline
  • dt.process.executable
  • dt.process.name
  • dt.security_context
  • dt.source_entity
  • dt.source_entity_name
  • dt.source_entity_type
  • event.unique_identifier
  • faas.id
  • faas.instance
  • faas.name
  • faas.version
  • gcp.instance.id
  • gcp.instance.name
  • gcp.project.id
  • gcp.region
  • gcp.resource.type
  • geo.city_name
  • geo.country_name
  • geo.name
  • geo.region_name
  • host.hostname
  • host.id
  • host.image.id
  • host.image.name
  • host.image.version
  • host.name
  • host.type
  • http.client_ip
  • http.flavor
  • http.host
  • http.method
  • http.route
  • http.scheme
  • http.server_name
  • http.status_code
  • http.status_text
  • http.target
  • http.url
  • journald.unit
  • k8s.cluster.name
  • k8s.container.name
  • k8s.cronjob.name
  • k8s.cronjob.uid
  • k8s.daemonset.name
  • k8s.daemonset.uid
  • k8s.deployment.name
  • k8s.deployment.uid
  • k8s.job.name
  • k8s.job.uid
  • k8s.namespace.name
  • k8s.pod.name
  • k8s.pod.uid
  • k8s.replicaset.name
  • k8s.replicaset.uid
  • k8s.statefulset.name
  • k8s.statefulset.uid
  • k8s.workload.kind
  • k8s.workload.name
  • log.source
  • log.source.origin
  • net.host.ip
  • net.host.name
  • net.host.port
  • net.peer.ip
  • net.peer.name
  • net.peer.port
  • net.transport
  • process.technology
  • service.instance.id
  • service.name
  • service.namespace
  • service.version
  • snmp.trap_oid
  • span_id
  • trace_id
  • winlog.eventid
  • winlog.keywords
  • winlog.level
  • winlog.opcode
  • winlog.provider
  • winlog.task
  • winlog.username

Модель JSON тела запроса

Это модель тела запроса, демонстрирующая возможные элементы. Её необходимо адаптировать для использования в реальном запросе.

[

  {

    "content": "Exception: Custom error log sent via Generic Log Ingest",

    "log.source": "/var/log/syslog",

    "timestamp": "2022-01-17T22:12:31.0000",

    "severity": "error",

    "custom.attribute": "attribute value"

  },

  {

    "content": "Exception: Custom error log sent via Generic Log Ingest",

    "log.source": "/var/log/syslog",

    "timestamp": "2022-01-17T22:12:35.0000"

  },

  {

    "content": "Exception: Custom error log sent via Generic Log Ingest",

    "log.source": "/var/log/syslog"

  },

  {

    "content": "Exception: Custom error log sent via Generic Log Ingest"

  }

]

Ответы

Коды ответов

Код Тип Описание
200 Success

Envelope

Из-за невалидности событий была принята только часть входных событий. Подробности см. в тексте ответа.
204 - Успех. У ответа нет тела.
400 Error

Envelope

Ошибка. Введенные данные недействительны.
402 Error

Envelope

Ошибка. Это связано либо со статусом вашего лицензионного соглашения, либо с тем, что вы исчерпали срок действия своей лицензии DPS.
404 Error

Envelope

Ошибка. Запрошенный ресурс не существует. Это может произойти, если АктивныйШлюз недоступен при включённом модуле Log Analytics Collector.
413 Error

Envelope

Ошибка. Размер полезной нагрузки запроса слишком велик. Это может произойти, если размер полезной нагрузки превышает ограничение или если полученная полезная нагрузка представляет собой JSON-массив, размер которого превышает ограничение.
429 Error

Envelope

Ошибка. Слишком много запросов. Это может произойти, если АктивныйШлюз не может обработать больше запросов в данный момент или если приём логов отключён. Возможность повтора с использованием стратегии экспоненциального откладывания.
501 Error

Envelope

Ошибка. Сервер либо не распознаёт метод запроса, либо не может его выполнить. В Log Monitoring Classic это может произойти, если не включено индексированное хранилище логов.
503 Error

Envelope

Ошибка. Сервер в данный момент не может обработать запрос. Это может произойти из-за перегрузки АктивногоШлюза. Повторите попытку, используя стратегию экспоненциальной задержки.
4ХХ Error

Envelope

Ошибка на стороне клиента.
5XX Error

Envelope

Ошибка на стороне сервера.

Объекты тела запроса

Объект SuccessEnvelope​

Элемент Тип Описание
details Success -

Объект Success​

Элемент Тип Описание
code integer Код статуса HTTP
message string Подробное сообщение

Модель JSON тела запроса

{

  "details": {

    "code": 1,

    "message": "string"

  }

}

Источник — https://doc.fit4u.kz/index.php?title=API_мониторинг_логов_-_POST_прием_логов&oldid=5652