Агрегации

seq-db поддерживает различные типы агрегаций: функциональные агрегации, гистограммы и таймсерии (временные ряды). Каждый из этих типов опирается на использование обратного индекса, поэтому для вычисления агрегаций по полям поле должно быть проиндексировано.

Функциональные агрегации

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

seq-db поддерживает различные функции агрегации:

• AGG_FUNC_SUM — сумма значений поля
• AGG_FUNC_AVG — среднее значение поля
• AGG_FUNC_MIN — минимальное значение поля
• AGG_FUNC_MAX — максимальное значение поля
• AGG_FUNC_QUANTILE — квантиль поля
• AGG_FUNC_UNIQUE — уникальные значения поля (не работает у таймсерий)
• AGG_FUNC_COUNT — количество документов для каждого уникального значения поля

Для ознакомления с API функций обратитесь к документации публичного API

Чтобы лучше понять, как работают агрегации, проиллюстрируем примеры с аналогичными SQL-запросами.

Sum, average, minimum, maximum, quantile

Вычисление вышеупомянутых агрегаций требует:

• AGG_FUNC - одна из функций AGG_FUNC_SUM, AGG_FUNC_AVG, AGG_FUNC_MIN, AGG_FUNC_MAX, AGG_FUNC_QUANTILE,
• aggregate_by_field - поле, к которому применяется агрегация
• group_by_field - поле, по которому группируются значения (используется не для всех агрегаций)
• filtering_query- запрос чтобы отфильтровать только интересующие нас логи
• quantile - только для AGG_FUNC_QUANTILE

В общем случае это преобразуется в следующий SQL-запрос:

SELECT <group_by_field>, AGG_FUNC(<aggregate_by_field>)
FROM db
WHERE <filtering_query>
GROUP BY <group_by_field>

Используя наш API:

grpcurl -plaintext -d '
{
  "query": {
    "from": "2000-01-01T00:00:00Z",
    "to": "2077-01-01T00:00:00Z",
    "query": "<filtering_query>"
  },
  "aggs": [
    {
      "field": "<aggregate_by_field>",
      "func": "AGG_FUNC",
      "group_by": "<group_by_field>"
    }
  ]
}' localhost:9004 seqproxyapi.v1.SeqProxyApi/GetAggregation

Рассматривая реальный пример, нам может потребоваться вычислить среднее время ответа для сервисов, имеющих поле response_time. Тогда мы бы написали следующий запрос:

SELECT service, AVG(response_time)
FROM db
WHERE response_time:* -- meaning that `response_time` field exists in logs
GROUP BY service

Используя наш API:

grpcurl -plaintext -d '
{
  "query": {
    "from": "2000-01-01T00:00:00Z",
    "to": "2077-01-01T00:00:00Z",
    "query": "response_time:*"
  },
  "aggs": [
    {
      "field": "response_time",
      "func": "AGG_FUNC_AVG",
      "group_by": "service"
    }
  ]
}' localhost:9004 seqproxyapi.v1.SeqProxyApi/GetAggregation

Count, unique

Агрегации Count и Unique очень похожи на приведенные выше примеры, за исключением того, что для этих агрегаций нет необходимости в дополнительном group_by_field, поскольку мы уже группируем по aggregate_by_field.

SQL-запрос для агрегации AGG_FUNC_COUNT:

SELECT <aggregate_by_field>, COUNT (*)
FROM db
WHERE <filtering_query>
GROUP BY <aggregate_by_field>

Используя наш API:

grpcurl -plaintext -d '
{
  "query": {
    "from": "2000-01-01T00:00:00Z",
    "to": "2077-01-01T00:00:00Z",
    "query": "<filtering_query>"
  },
  "aggs": [
    {
      "field": "<aggregate_by_field>",
      "func": "AGG_FUNC_COUNT"
    }
  ]
}' localhost:9004 seqproxyapi.v1.SeqProxyApi/GetAggregation

Рассматривая реальный пример, мы можем захотеть вычислить количество логов для каждого уровня логирования (debug, info и т.д.) для определенного сервиса, например, seq-db. Тогда мы можем написать следующий запрос:

SELECT level, COUNT(*)
FROM db
WHERE service:seq-db
GROUP BY level

Используя наш API:

grpcurl -plaintext -d '
{
  "query": {
    "from": "2000-01-01T00:00:00Z",
    "to": "2077-01-01T00:00:00Z",
    "query": "service:seq-db"
  },
  "aggs": [
    {
      "field": "level",
      "func": "AGG_FUNC_COUNT"
    }
  ]
}' localhost:9004 seqproxyapi.v1.SeqProxyApi/GetAggregation

Гистограммы

Гистограммы позволяют пользователям визуально интерпретировать распределение логов, удовлетворяющих заданному запросу. Например, количество логов определенного сервиса за заданный интервал времени.

Гистограммы можно запрашивать отдельно, используя GetHistogram, или вместе с документами и функциональными агрегациями, используя ComplexSearch.

Для более подробного ознакомления с API и примерами обратитесь к публичному API.

Таймсерии

Таймсерии позволяют вычислять агрегации для интервалов и визуализировать их. Они представляют собой нечто среднее между гистограммами и функциональными агрегациями: они позволяют одновременно вычислять несколько гистограмм для заданных функций агрегации.

Рассмотрим предыдущий пример с гистограммами, где мы визуализировали количество логов во времени только для одного сервиса за раз. Используя возможности таймсерий, мы можем одновременно вычислить количество логов для каждого сервиса, используя AGG_FUNC_COUNT по полю service.

Другой пример использования таймсерий — визуализация количества логов для каждого уровня логирования во времени. Это может быть особенно полезно, когда необходимо отлаживать проблемы в реальном времени. Мы можем просто визуализировать количество логов для каждого уровня и найти необычные всплески и связанные с ними логи.

Поскольку временные ряды по сути являются агрегациями, они имеют тот же API, что и агрегации, за исключением того, что присутствует новое поле interval для вычисления количества интервалов для расчета агрегации. Для получения подробной информации обратитесь к публичному API.