API мониторинга логов v2 — отправка логов методом POST
API мониторинга логов v2 — отправка логов методом POST
Отправляет пользовательские логи в Ключ-АСТРОМ.
Эта конечная точка доступна в вашей среде, или, в качестве альтернативы, вы можете предоставить к ней доступ через АктивныйШлюз в вашей среде с включенным модулем сбора логов. Этот модуль включен по умолчанию на всех ваших АктивныхШлюзах.
Запрос обрабатывает один из следующих типов полезной нагрузки:
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
https://{your-environment-id}.live.astromkey.com/api/v2/logs/ingest
POST Среда АктивныйШлюз Кластер АктивныйШлюз
https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/logs/ingest
Аутентификация
Для выполнения этого запроса вам потребуется токен доступа с областью действия logs.ingest.
Чтобы узнать, как получить и использовать его, см. раздел «Токены и аутентификация».
Параметры
При использовании обработки логов с пользовательским конвейером обработки (OpenPipeline) функция приема данных поддерживает все типы данных JSON для значений атрибутов. Это требует версии 1.295+ при использовании конечной точки API или АктивныйШлюз версии 1.295+ при использовании конечной точки API АктивногоШлюза. Во всех остальных случаях все передаваемые значения преобразуются в строковый тип.
| Параметр | Тип | Описание | В | Необходимый |
|---|---|---|---|---|
content-type |
строка | (Необязательно) Позволяет указать тип контента в качестве параметра запроса. Имеет приоритет над значением, указанным в заголовке Content-Type. | запрос | Необязательный |
structure |
строка | (Необязательно) Модель данных, используемая для структурирования входных данных в записи журнала. Допустимые значения: raw, flattened. Для получения более подробной информации см. документацию. |
запрос | Необязательный |
X-Astromkey-Attr |
строка | (Необязательно) Содержит пары ключ-значение, разделенные амперсандами, представляющие дополнительные атрибуты журнала, которые будут добавлены к каждой обработанной записи журнала. Если один и тот же ключ встречается несколько раз, все значения фиксируются как многозначный атрибут. Параметры запроса имеют приоритет над значениями, указанными в этом заголовке. Для получения более подробной информации см. документацию. | заголовок | Необязательный |
X-Astromkey-Options |
строка | (Необязательно) Содержит параметры, специфичные для Ключ-АСТРОМ, разделённые амперсандами. Поддерживаемые параметры: structure (значения: raw, flattened) определяет, как входные данные структурируются в записи журнала. Параметры запроса имеют приоритет над значениями заголовка. Для получения более подробной информации см. документацию. |
заголовок | Необязательный |
body |
Сообщение лога в формате JSON | Тело запроса. Содержит одно или несколько событий журнала, подлежащих обработке. Данная конечная точка принимает один из следующих типов полезной нагрузки, определяемых заголовком Accept: text/plain — поддерживает только одно событие в журнале; application/json — поддерживает несколько событий журнала в одном полезном массиве JSON; application/jsonl, application/jsonlines, application/x-ndjson, application/jsonlines+json или application/x-jsonlines — поддерживает несколько событий журнала в виде JSON-строк (один JSON-объект на строку). |
тело | Необязательный |
Запрос объектов тела
Объект LogMessageJson
Набор из одного или нескольких событий журнала:
- в формате JSON: массив JSON-объектов событий журнала, например:
[ { "message": "1" }, { "message": "2" } ]или отдельный JSON-объект события журнала, например:{ "message": "1" }. - В формате JSON-строк: последовательность JSON-объектов событий журнала, разделенных символами новой строки, например:
{ "message": "1" }
{ "message": "2" }
События журнала из входных данных сопоставляются с записями журнала Ключ-АСТРОМ, содержащими три специальных атрибута: метку времени, уровень логирования и содержимое, а также карту других атрибутов. Эти четыре свойства устанавливаются на основе ключей, присутствующих во входном JSON-объекте. Для получения более подробной информации обратитесь к документации.
Обработка атрибутов зависит от модели данных, используемой для обработки входных данных. Эффективная модель данных для конкретного запроса зависит от параметра structure или модели данных арендатора по умолчанию, которая определяется конфигурацией арендатора. Более подробную информацию можно найти в документации.
JSON-модель тела запроса
Это модель тела запроса, демонстрирующая возможные элементы. Её необходимо адаптировать для использования в реальном запросе.
[
{
"content": "Exception: Custom error log sent via generic log ingest mechanism",
"log.source": "/var/log/syslog",
"timestamp": "2025-12-17T22:12:31.0000",
"severity": "error",
"custom.attribute": "attribute value",
"complex": {
"key-1": "attribute value-1",
"key-2": 234.2
},
"array.attr": [
"value-1",
1,
null,
true,
[1, 2, 3],
{"key": "value"}
]
},
{
"message": "User 1 logged in successfully",
"log.source": "/var/log/syslog",
"@timestamp": "1765281600"
},
{
"Payload": "Exception: Custom error log sent via generic log ingest mechanism",
"log.source": "/var/log/syslog"
},
{
"log": "My log message without extra attributes"
}
]
Ответ
Коды ответов
| Код | Тип | Описание |
|---|---|---|
| 200 | SuccessEnvelope | Из-за недействительности событий была обработана лишь часть входных событий. Подробности см. в теле ответа. |
| 204 | – | Успех. Ответ не имеет тела. |
| 400 | ErrorEnvelope | Ошибка. Введенные данные недопустимы. |
| 402 | ErrorEnvelope | Неудачно. Это связано либо со статусом вашего лицензионного соглашения, либо с тем, что вы исчерпали срок действия вашей лицензии DPS. |
| 404 | ErrorEnvelope | Сбой. Запрошенный ресурс не существует. Это может произойти, если модуль Log Analytics Collector недоступен. |
| 413 | ErrorEnvelope | Сбой. Размер запрошенной полезной нагрузки слишком велик. Это может произойти, если размер полезной нагрузки в байтах превышает лимит или если полученная полезная нагрузка представляет собой массив JSON, размер которого превышает лимит. |
| 429 | ErrorEnvelope | Сбой. Слишком много запросов. Это может произойти, когда АктивныйШлюз не может обработать больше запросов в данный момент или когда прием логов отключен. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 501 | ErrorEnvelope | Сбой. Сервер либо не распознает метод запроса, либо не имеет возможности выполнить запрос. В Log Monitoring Classic это может произойти, если индексированное хранилище логов не включено. |
| 502 | – | Сбой. Неверный шлюз. Это может произойти, если промежуточная система (например, АктивныйШлюз или прокси-сервер) столкнется с проблемой при пересылке запроса. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 503 | ErrorEnvelope | Сбой. Сервер в данный момент не может обработать запрос. Это может произойти при перегрузке АктивногоШлюза. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 504 | – | Сбой. Таймаут шлюза. Это может произойти из-за проблемы в базовой инфраструктуре, вызывающей задержку в обработке запроса. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 4XX | ErrorEnvelope | Ошибка на стороне клиента. |
| 5XX | ErrorEnvelope | Ошибка на стороне сервера. |
Объекты тела ответа
Объект SuccessEnvelope
| Элемент | Тип | Описание |
|---|---|---|
details |
Success |
– |
Объект Success
| Элемент | Тип | Описание |
|---|---|---|
code |
целое число | Код состояния HTTP |
message |
строка | Подробное сообщение |
Объект ErrorEnvelope
| Элемент | Тип | Описание |
|---|---|---|
error |
Error |
– |
Объект Error
| Элемент | Тип | Описание |
|---|---|---|
code |
целое число | Код состояния HTTP |
constraintViolations |
ConstraintViolation[] |
Список нарушений ограничений |
message |
строка | Сообщение об ошибке |
Объект ConstraintViolation
Список нарушений ограничений
| Элемент | Тип | Описание |
|---|---|---|
location |
строка | – |
message |
строка | – |
parameterLocation |
строка | Этот элемент может содержать следующие значения |
path |
строка | – |
Модели JSON тела ответа
{
"details": {
"code": 1,
"message": "string"
}
}
{
"error": {
"code": 1,
"constraintViolations": [
{
"location": "string",
"message": "string",
"parameterLocation": "HEADER",
"path": "string"
}
],
"message": "string"
}
}
Аутентификация
Для выполнения этого запроса вам потребуется токен доступа с областью действия logs.ingest.
Чтобы узнать, как получить и использовать его, см. раздел «Токены и аутентификация».
Параметры
При использовании обработки логов с пользовательским конвейером обработки (OpenPipeline) функция приема данных поддерживает все типы данных JSON для значений атрибутов. Это требует... Версия SaaS 1.295+ при использовании конечной точки API SaaS или АктивныйШлюз версии 1.295+ при использовании конечной точки API АктивногоШлюза. Во всех остальных случаях все передаваемые значения преобразуются в строковый тип.
| Параметр | Тип | Описание | В | Необходимый |
|---|---|---|---|---|
content-type |
строка | (Необязательно) Позволяет указать тип контента в качестве параметра запроса. Имеет приоритет над значением, указанным в заголовке Content-Type. | запрос | Необязательный |
structure |
строка | (Необязательно) Модель данных, используемая для структурирования входных данных в записи журнала. Допустимые значения: raw, flattened. Для получения более подробной информации см. документацию. |
запрос | Необязательный |
X-Astromkey-Attr |
строка | (Необязательно) Содержит пары ключ-значение, разделенные амперсандами, представляющие дополнительные атрибуты журнала, которые будут добавлены к каждой обработанной записи журнала. Если один и тот же ключ встречается несколько раз, все значения фиксируются как многозначный атрибут. Параметры запроса имеют приоритет над значениями, указанными в этом заголовке. Для получения более подробной информации см. документацию. | заголовок | Необязательный |
X-Astromkey-Options |
строка | (Необязательно) Содержит параметры, специфичные для Ключ-АСТРОМ, разделённые амперсандами. Поддерживаемые параметры: (только для SaaS) structure (значения: raw, flattened) определяет, как входные данные структурируются в записи журнала. Параметры запроса имеют приоритет над значениями заголовка. Для получения более подробной информации см. документацию. |
заголовок | Необязательный |
body |
Сообщение лога в формате JSON | Тело запроса. Содержит одно или несколько событий журнала, подлежащих обработке. Данная конечная точка принимает один из следующих типов полезной нагрузки, определяемых заголовком Accept: text/plain — поддерживает только одно событие в журнале; application/json — поддерживает несколько событий журнала в одном полезном массиве JSON; application/jsonl, application/jsonlines, application/x-ndjson, application/jsonlines+json или application/x-jsonlines — поддерживает несколько событий журнала в виде JSON-строк (один JSON-объект на строку). |
тело | Необязательный |
Запрос объектов тела
Объект LogMessageJson
Набор из одного или нескольких событий журнала:
- в формате JSON: массив JSON-объектов событий журнала, например:
[ { "message": "1" }, { "message": "2" } ]или отдельный JSON-объект события журнала, например:{ "message": "1" }. - В формате JSON-строк: последовательность JSON-объектов событий журнала, разделенных символами новой строки, например:
{ "message": "1" }
{ "message": "2" }
События журнала из входных данных сопоставляются с записями журнала Ключ-АСТРОМ, содержащими три специальных атрибута: метку времени, уровень логирования и содержимое, а также карту других атрибутов. Эти четыре свойства устанавливаются на основе ключей, присутствующих во входном JSON-объекте. Для получения более подробной информации обратитесь к документации.
(Только для SaaS) Обработка атрибутов зависит от модели данных, используемой для обработки входных данных. Эффективная модель данных для конкретного запроса зависит от параметра structure или модели данных арендатора по умолчанию, которая определяется конфигурацией арендатора. Более подробную информацию можно найти в документации.
JSON-модель тела запроса
Это модель тела запроса, демонстрирующая возможные элементы. Её необходимо адаптировать для использования в реальном запросе.
[
{
"content": "Exception: Custom error log sent via generic log ingest mechanism",
"log.source": "/var/log/syslog",
"timestamp": "2025-12-17T22:12:31.0000",
"severity": "error",
"custom.attribute": "attribute value",
"complex": {
"key-1": "attribute value-1",
"key-2": 234.2
},
"array.attr": [
"value-1",
1,
null,
true,
[1, 2, 3],
{"key": "value"}
]
},
{
"message": "User 1 logged in successfully",
"log.source": "/var/log/syslog",
"@timestamp": "1765281600"
},
{
"Payload": "Exception: Custom error log sent via generic log ingest mechanism",
"log.source": "/var/log/syslog"
},
{
"log": "My log message without extra attributes"
}
]
Ответ
Коды ответов
| Код | Тип | Описание |
|---|---|---|
| 200 | Конверт успеха | Из-за недействительности событий была обработана лишь часть входных событий. Подробности см. в теле ответа. |
| 204 | – | Успех. Ответ не имеет тела. |
| 400 | Оболочка ошибки | Ошибка. Введенные данные недопустимы. |
| 402 | Оболочка ошибки | Неудачно. Это связано либо со статусом вашего лицензионного соглашения, либо с тем, что вы исчерпали срок действия вашей лицензии DPS. |
| 404 | Оболочка ошибки | Сбой. Запрошенный ресурс не существует. Это может произойти, если модуль Log Analytics Collector недоступен. |
| 413 | Оболочка ошибки | Сбой. Размер запрошенной полезной нагрузки слишком велик. Это может произойти, если размер полезной нагрузки в байтах превышает лимит или если полученная полезная нагрузка представляет собой массив JSON, размер которого превышает лимит. |
| 429 | Оболочка ошибки | Сбой. Слишком много запросов. Это может произойти, когда АктивныйШлюз не может обработать больше запросов в данный момент или когда прием логов отключен. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 501 | Оболочка ошибки | Сбой. Сервер либо не распознает метод запроса, либо не имеет возможности выполнить запрос. В Log Monitoring Classic это может произойти, если индексированное хранилище логов не включено. |
| 502 | – | Сбой. Неверный шлюз. Это может произойти, если промежуточная система (например, АктивныйШлюз или прокси-сервер) столкнется с проблемой при пересылке запроса. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 503 | Оболочка ошибки | Сбой. Сервер в данный момент не может обработать запрос. Это может произойти при перегрузке АктивногоШлюза. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 504 | – | Сбой. Таймаут шлюза. Это может произойти из-за проблемы в базовой инфраструктуре, вызывающей задержку в обработке запроса. Возможна повторная попытка с использованием стратегии экспоненциальной задержки. |
| 4XX | Оболочка ошибки | Ошибка на стороне клиента. |
| 5XX | Оболочка ошибки | Ошибка на стороне сервера. |
Объекты тела ответа
Объект SuccessEnvelope
| Элемент | Тип | Описание |
|---|---|---|
details |
Success |
– |
Объект Success
| Элемент | Тип | Описание |
|---|---|---|
code |
целое число | Код состояния HTTP |
message |
строка | Подробное сообщение |
Объект ErrorEnvelope
| Элемент | Тип | Описание |
|---|---|---|
error |
Error |
– |
Объект Error
| Элемент | Тип | Описание |
|---|---|---|
code |
целое число | Код состояния HTTP |
constraintViolations |
ConstraintViolation[] |
Список нарушений ограничений |
message |
строка | Сообщение об ошибке |
Объект ConstraintViolation
Список нарушений ограничений
| Элемент | Тип | Описание |
|---|---|---|
location |
строка | – |
message |
строка | – |
parameterLocation |
строка | Этот элемент может содержать следующие значения |
path |
строка | – |
Модели JSON тела ответа
{
"details": {
"code": 1,
"message": "string"
}
}
{
"error": {
"code": 1,
"constraintViolations": [
{
"location": "string",
"message": "string",
"parameterLocation": "HEADER",
"path": "string"
}
],
"message": "string"
}
}
