Публичное API
Введение
seq-db состоит и з двух компонентов - proxy и store:
- seq-db proxy и seq-db store взаимодействуют через внутреннее seq-db store gRPC API.
- Поиск логов происходит при помощи seq-db proxy gRPC API.
- Прием логов происходит при помощи Elasticsearch совместимого HTTP API
- Для целей отладки seq-db proxy имеет
HTTP API
, похожее наgRPC API
В этом документе описаны seq-db ingestion API
и seq-db search API
Bulk HTTP API
seq-db совместима с Elasticsearch bulk API
/
Возвращает захардкоженный ответ, указывающий на версию используемого Elasticsearch. Это позволяет использовать seq-db в качестве Elasticsearch вывода для logstash, filebeat и других инструментов доставки логов.
Пример запроса:
curl -X GET http://localhost:9002/
Пример успешного ответа:
{
"cluster_name": "seq-db",
"version": {
"number": "8.9.0"
}
}
/_bulk
Принимает тело запроса, разбирает его на документы и метаданные, затем записывает в хранилища через внутренний API.
Пример запроса:
curl -X POST http://localhost:9002/_bulk -d '
{"index":""}
{"k8s_pod":"seq-proxy", "request_time": "5", "time": "2024-12-23T18:00:36.357Z"}
{"index":""}
{"k8s_pod":"seq-proxy", "request_time": "6"}
{"index":""}
{"k8s_pod":"seq-proxy", "request_time": "7"}
{"index":""}
{"k8s_pod":"seq-proxy", "request_time": "8"}
{"index":""}
{"k8s_pod":"seq-proxy", "request_time": "9"}
{"index":""}
{"k8s_pod":"seq-db", "request_time": "10"}
{"index":""}
{"k8s_pod":"seq-db", "request_time": "11"}
{"index":""}
{"k8s_pod":"seq-db", "request_time": "12"}
{"index":""}
{"k8s_pod":"seq-db", "request_time": "13"}
{"index":""}
{"k8s_pod":"seq-db", "request_time": "14"}
'
Пример успешного ответа:
{
"took": 11,
"errors": false,
"items": [
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } },
{ "create": { "status": 201 } }
]
}
Можно заметить, что в поле index
нет данных: seq-db игнорирует это поле, потому что использует маппинг для индексации полей.
Больше о маппинге и индексах можно прочитать в документации
Пример ответа при превышении лимита запросов:
Не должно быть более consts.IngestorMaxInflightBulks
(по умолчанию 32) одновременных запросов, в противном случае
запрос будет ограничен по частоте, и seq-db ответит кодом ответа 429
.
Пример ответа с ошибкой:
В случае ошибки, seq-db вернет код ответа 500
и сообщение об ошибке.
Например, при попытке вставить некорректный json:
curl -v -X POST http://localhost:9002/_bulk -d '
{"index":""}
{"k8s_pod":"seq-proxy", "request_time": "123}
'
мы получим
processing doc: unexpected end of string near `", "request_time": "123`
^
Search gRPC API
/Search
Метод поиска документов. Принимает поисковый запрос в формате seq-ql и возвращает документы, удовлетворяющие поисковому запросу.
Пример запроса:
grpcurl -plaintext -d '
{
"query": {
"from": "2020-01-01T00:00:00Z",
"to": "2030-01-01T00:00:00Z",
"query": "k8s_pod:seq-db"
},
"size": 2,
"with_total": true
}' localhost:9004 seqproxyapi.v1.SeqProxyApi/Search
Пример успешного ответа:
{
"total": "5",
"docs": [
{
"id": "0593adf493010000-d901eee224290dc6",
"data": "eyJrOHNfcG9kIjoic2VxLWRiIiwgInJlcXVlc3RfdGltZSI6ICIxMyJ9",
"time": "2024-12-23T18:00:36.357Z"
},
{
"id": "0593adf493010000-d9013865e424dba1",
"data": "eyJrOHNfcG9kIjoic2VxLWRiIiwgInJlcXVlc3RfdGltZSI6ICIxMSJ9",
"time": "2024-12-23T18:00:36.357Z"
}
],
"error": {
"code": "ERROR_CODE_NO"
}
}
Поле data
содержит оригинальный документ, закодированный в base64. Если декодировать его,
echo 'eyJrOHNfcG9kIjoic2VxLWRiIiwgInJlcXVlc3RfdGltZSI6ICIxMyJ9' | base64 -d | jq
то получится
{
"k8s_pod": "seq-db",
"request_time": "13"
}
/GetAggregation
Агрегации позволяют вычислять статистические значения (сумма, среднее, максимум, минимум, квантиль, уникальность, количество) по полям документов, соответствующим запросу. Также агрегации поддерживают вычисление статистических значений среди различных временных интервалов (также известные как таймсерии).
Агрегации можно вызывать двумя способами:
- через отдельный gRPC обработчик:
GetAggregation
- вместе с поиском и гистограммами:
ComplexSearch
В примерах используется API
GetAggregation
, которая по структуре запроса и ответа совпадает сComplexSearch
.
Поддерживаемые функции агрегации:
AGG_FUNC_SUM
— сумма значений поляAGG_FUNC_AVG
— среднее значение поляAGG_FUNC_MIN
— минимальное значение поляAGG_FUNC_MAX
— максимальное значение поляAGG_FUNC_QUANTILE
— вычисление квантилей для поляAGG_FUNC_UNIQUE
— вычисление уникальных значений поля (не поддерживается для вычисления таймсерий)AGG_FUNC_COUNT
— подсчёт количества документов по группе
Примеры агрегаций
Исходные документы:
{"service": "svc1", "latency": 100}
{"service": "svc1", "latency": 300}
{"service": "svc2", "latency": 400}
{"service": "svc2", "latency": 200}
{"service": "svc3", "latency": 500}
Вычисление SUM, AVG, MIN, MAX
Запрос:
grpcurl -plaintext -d '
{
"query": {
"from": "2000-01-01T00:00:00Z",
"to": "2077-01-01T00:00:00Z",
"query": "*"
},
"aggs": [
{
"field": "latency",
"func": "AGG_FUNC_SUM"
},
{
"field": "latency",
"func": "AGG_FUNC_AVG"
},
{
"field": "latency",
"func": "AGG_FUNC_MIN"
},
{
"field": "latency",
"func": "AGG_FUNC_MAX"
}
]
}' localhost:9004 seqproxyapi.v1.SeqProxyApi/GetAggregation
Ответ:
{
"aggs": [
{
"buckets": [
{"value": 1500}
]
},
{
"buckets": [
{"value": 300}
]
},
{
"buckets": [
{"value": 100}
]
},
{
"buckets": [
{"value": 500}
]
}
]
}