LogSense

Тема

API Reference ​

LogSense открывает REST API вместе с коллектором. Через него можно добавлять источники, отправлять события и выполнять поиск.

Общие правила ​

Базовый адрес: http://127.0.0.1:4173/api/v1.

  • запросы и ответы используют application/json;
  • время передаётся в UTC по RFC 3339;
  • идентификаторы событий имеют формат ULID;
  • размер JSON-запроса ограничен 8 МБ;
  • список возвращает не больше 500 записей за запрос.

Формат события ​

У события есть пять основных полей. Остальные поля хранятся в attributes.

json
{
  "id": "01J4Z2M8X6P5Q1QW9D6GJH7T3A",
  "time": "2026-07-31T09:12:03.248Z",
  "level": "error",
  "service": "gateway",
  "message": "upstream timeout",
  "attributes": {
    "host": "edge-02",
    "latency_ms": 3000,
    "trace_id": "8f2a"
  }
}

Допустимые уровни: trace, debug, info, warn, error и fatal.

Состояние процесса ​

GET /health ​

Возвращает состояние коллектора и индекса. Метод не меняет данные.

json
{
  "status": "ok",
  "version": "0.8.0",
  "uptime_seconds": 86412,
  "index": {
    "events": 12840,
    "segments": 24,
    "size_bytes": 9437184,
    "last_compaction": "2026-07-31T08:00:00Z"
  },
  "sources": {
    "running": 3,
    "paused": 1,
    "failed": 0
  }
}

Источники ​

GET /sources ​

Возвращает все настроенные источники. Для каждого источника видны состояние и позиция чтения.

json
{
  "items": [
    {
      "id": "api-jsonl",
      "type": "file",
      "path": "/var/log/apps/api.jsonl",
      "status": "running",
      "offset": 481920,
      "events_read": 18422,
      "parse_errors": 3
    }
  ]
}

POST /sources ​

Создаёт источник и сразу запускает чтение. Поле id должно быть уникальным.

json
{
  "id": "worker-jsonl",
  "type": "file",
  "path": "/var/log/apps/worker.jsonl",
  "format": "jsonl",
  "start_at": "end",
  "fields": {
    "time": "timestamp",
    "level": "severity",
    "message": "msg"
  }
}

Успешный ответ имеет код 201.

json
{
  "id": "worker-jsonl",
  "status": "running",
  "offset": 0
}

PATCH /sources/{id} ​

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

json
{
  "status": "paused"
}

Значение running продолжает чтение. Значение paused сохраняет текущую позицию.

DELETE /sources/{id} ​

Удаляет источник из конфигурации. Уже записанные события остаются в индексе.

Параметр purge=true удаляет события этого источника. Операция возвращает 202.

Запись событий ​

POST /events ​

Принимает одно событие или массив. Поле id можно пропустить.

json
[
  {
    "time": "2026-07-31T09:12:03Z",
    "level": "error",
    "service": "gateway",
    "message": "upstream timeout",
    "attributes": {
      "trace_id": "8f2a",
      "latency_ms": 3000
    }
  },
  {
    "time": "2026-07-31T09:12:04Z",
    "level": "warn",
    "service": "worker",
    "message": "retry scheduled"
  }
]

Ответ показывает результат всей пачки.

json
{
  "accepted": 2,
  "rejected": 0,
  "ids": [
    "01J4Z2M8X6P5Q1QW9D6GJH7T3A",
    "01J4Z2M9A9A2K4QT4MZH2T5K9J"
  ]
}

При частичной ошибке метод возвращает 207. Массив errors содержит индекс записи и причину отказа.

Поиск событий ​

GET /events ​

Ищет события в локальном индексе. Фильтры можно комбинировать.

ПараметрТипОписание
querystringСлова или точная фраза в кавычках
servicestringОдно или несколько имён через запятую
levelstringТочный уровень или выражение gte:warn
hoststringЗначение attributes.host
trace_idstringИдентификатор трассировки
fromdatetimeНачало временного диапазона
todatetimeКонец временного диапазона
hasstringПоле, которое должно присутствовать
sortstringtime:asc или time:desc
limitintegerОт 1 до 500, по умолчанию 100
cursorstringКурсор следующей страницы
http
GET /api/v1/events?service=gateway,worker&level=gte:warn&query=%22timeout%22&limit=50 HTTP/1.1
Host: 127.0.0.1:4173
Accept: application/json
json
{
  "items": [
    {
      "id": "01J4Z2M8X6P5Q1QW9D6GJH7T3A",
      "time": "2026-07-31T09:12:03.248Z",
      "level": "error",
      "service": "gateway",
      "message": "upstream timeout",
      "attributes": {
        "host": "edge-02",
        "latency_ms": 3000,
        "trace_id": "8f2a"
      }
    }
  ],
  "next_cursor": "eyJ0aW1lIjoiMjAyNi0wNy0zMVQwOToxMjowMy4yNDhaIn0",
  "took_ms": 7
}

Курсор привязан к фильтрам. При их изменении начните поиск без cursor.

GET /events/{id} ​

Возвращает одно событие по ULID. Удалённое событие даёт ответ 404.

DELETE /events/{id} ​

Удаляет событие из активного сегмента. Метод возвращает 204.

Трассировки ​

GET /traces/{traceId} ​

Возвращает события с одинаковым trace_id. Результат отсортирован по времени.

json
{
  "trace_id": "8f2a",
  "started_at": "2026-07-31T09:12:02.901Z",
  "duration_ms": 3347,
  "services": ["gateway", "api", "postgres"],
  "events": [
    {
      "id": "01J4Z2M7VMBVA9X7X2YFQ88S6P",
      "time": "2026-07-31T09:12:02.901Z",
      "level": "info",
      "service": "gateway",
      "message": "request started"
    }
  ]
}

Параметр include=attributes добавляет атрибуты каждого события.

Статистика ​

GET /stats/services ​

Группирует события по сервису. Интервал задают параметры from и to.

json
{
  "items": [
    {
      "service": "gateway",
      "events": 8412,
      "errors": 43,
      "error_rate": 0.0051
    },
    {
      "service": "worker",
      "events": 2921,
      "errors": 8,
      "error_rate": 0.0027
    }
  ]
}

GET /stats/levels ​

Возвращает количество событий по уровням. Параметр interval принимает 1m, 5m, 1h или 1d.

GET /stats/volume ​

Строит временной ряд количества событий. Фильтры совпадают с GET /events.

http
GET /api/v1/stats/volume?service=gateway&interval=5m&from=2026-07-31T08:00:00Z HTTP/1.1
Host: 127.0.0.1:4173
Accept: application/json

Сохранённые запросы ​

GET /saved-queries ​

Возвращает список сохранённых запросов. Порядок совпадает с датой изменения.

POST /saved-queries ​

Сохраняет фильтры под выбранным именем.

json
{
  "name": "Ошибки gateway за час",
  "filters": {
    "service": ["gateway"],
    "level": "gte:error",
    "range": "1h"
  }
}

Ответ 201 содержит созданный объект.

json
{
  "id": "sq_gateway_errors",
  "name": "Ошибки gateway за час",
  "created_at": "2026-07-31T09:20:00Z",
  "filters": {
    "service": ["gateway"],
    "level": "gte:error",
    "range": "1h"
  }
}

DELETE /saved-queries/{id} ​

Удаляет сохранённый запрос. События и индекс не меняются.

Обслуживание индекса ​

POST /index/compact ​

Запускает слияние небольших сегментов. Метод отвечает 202.

json
{
  "job_id": "compact_01J4Z2Q2H7YPR5N8TQQ2JQK4W3",
  "status": "queued"
}

GET /index/jobs/{jobId} ​

Возвращает состояние обслуживания. Готовое задание содержит освобождённый объём.

json
{
  "id": "compact_01J4Z2Q2H7YPR5N8TQQ2JQK4W3",
  "status": "completed",
  "segments_before": 48,
  "segments_after": 12,
  "bytes_reclaimed": 7340032
}

Коды ответов ​

КодЗначение
200Запрос выполнен
201Объект создан
202Задание принято
204Объект удалён
207Часть пачки отклонена
400Параметры не прошли проверку
404Объект не найден
409Идентификатор уже занят
413Запрос превышает 8 МБ
429Превышен лимит запросов
500Внутренняя ошибка LogSense

Ошибки используют один формат. Поле details необязательно.

json
{
  "error": {
    "code": "invalid_time_range",
    "message": "Параметр from должен быть меньше to",
    "details": {
      "from": "2026-07-31T10:00:00Z",
      "to": "2026-07-31T09:00:00Z"
    }
  }
}