Модуль доступен только в Deckhouse Enterprise Edition.
Аутентификация
Эндпоинты, требующие аутентификации, должны вызываться с указанием заголовка HTTP-запроса X-Auth-Token
, содержащего API-токен.
Метрики
Отправка метрик
Для отправки метрик поддерживается протокол: Prometheus Remote-Write.
Пример запроса:
POST /api/v1/push
Этот эндпоинт принимает HTTP POST-запрос. Данные запроса закодированы с использованием Protocol Buffers и сжаты с помощью Snappy. Определение protobuf-сообщения можно найти в файле pkg/mimirpb/mimir.proto
. HTTP-запрос должен содержать заголовок X-Prometheus-Remote-Write-Version
с версией 0.1.0
.
Просмотр метрик
Общий формат
Instant queries
Этот эндпоинт выполняет мгновенный запрос на указанную точку времени.
Пример запроса:
GET /prometheus/api/v1/query
POST /prometheus/api/v1/query
Параметры запроса в URL:
query=<string>
: строка выражения запроса Prometheus.time=<rfc3339 | unix_timestamp>
: отметка времени для выполнения запроса. Опционально.timeout=<duration>
: время ожидания выполнения запроса. Опционально. По умолчанию ограничено значением флага-query.timeout
.
Если параметр time
пропущен, используется текущее время сервера.
Вы можете закодировать параметры запроса непосредственно в теле запроса, используя метод POST
и заголовок Content-Type: application/x-www-form-urlencoded
. Это полезно при указании больших запросов, которые могут превысить ограничение на длину URL.
Формат секции данных в результате запроса:
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}
<value>
относится к данным результатов запроса, формат которых зависит от resultType
. Смотри форматы результатов запросов выражений.
Пример:
Пример запроса для выполнения выражения up
на время 2015-07-01T20:10:51.781Z
:
$ curl -H "X-Auth-Token: <API-token>" \
'https://api.dop.example.com/prometheus/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
Ответ:
{
"status" : "success",
"data" : {
"resultType" : "vector",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"value": [ 1435781451.781, "1" ]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9100"
},
"value" : [ 1435781451.781, "0" ]
}
]
}
}
Range queries
Этот эндпоинт выполняет выражение запроса на диаграмму времени по диапазону:
GET /prometheus/api/v1/query_range
POST /prometheus/api/v1/query_range
Параметры URL:
query=<string>
: строка выражения Prometheus.start=<rfc3339 | unix_timestamp>
: начальная временная метка.end=<rfc3339 | unix_timestamp>
: конечная временная метка.step=<duration | float>
: шаг разрешения диаграммы (форматduration
или число секунд в формате float).timeout=<duration>
: время ожидания выполнения. Опционально.
Пример:
Пример запроса с выражением up
за 30-секундный диапазон с разрешением 15 секунд:
$ curl -H "X-Auth-Token: <API-token>" \
'https://api.dop.example.com/prometheus/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
Ответ:
{
"status" : "success",
"data" : {
"resultType" : "matrix",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"values" : [
[ 1435781430.781, "1" ],
[ 1435781445.781, "1" ],
[ 1435781460.781, "1" ]
]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9091"
},
"values" : [
[ 1435781430.781, "0" ],
[ 1435781445.781, "0" ],
[ 1435781460.781, "1" ]
]
}
]
}
}
Querying metadata
Deckhouse Observability Platform предоставляет несколько API для запроса метаданных о временных рядах и их метках.
Поиск ряда по набору меток
Эндпоинт возвращает список временных рядов, соответствующих определённому набору меток:
GET /prometheus/api/v1/series
POST /prometheus/api/v1/series
Параметры URL:
match[]=<series_selector>
: повторяющийся аргумент селектора, который выбирает возвращаемые ряды. Необходимо указать хотя бы один аргументmatch[]
.start=<rfc3339 | unix_timestamp>
: начальная временная метка.end=<rfc3339 | unix_timestamp>
: конечная временная метка.limit=<number>
: Максимальное количество возвращаемых рядов. По умолчанию 0, что означает отсутствие ограничения.
Пример:
$ curl -H "X-Auth-Token: <API-token>" \
-g 'https://api.dop.example.com/prometheus/api/v1/series?' \
--data-urlencode 'match[]=up' \
--data-urlencode 'match[]=process_start_time_seconds{job="prometheus"}'
Ответ:
{
"status" : "success",
"data" : [
{ "__name__" : "up", "job" : "prometheus", "instance" : "localhost:9090" },
{ "__name__" : "up", "job" : "node", "instance" : "localhost:9091" },
{ "__name__" : "process_start_time_seconds", "job" : "prometheus", "instance" : "localhost:9090" }
]
}
Получение имен меток
Этот эндпоинт возвращает список имен меток:
GET /prometheus/api/v1/labels
POST /prometheus/api/v1/labels
Пример:
$ curl -H "X-Auth-Token: <API-token>" \
'https://api.dop.example.com/prometheus/api/v1/labels'
Ответ:
{
"status": "success",
"data": [
"__name__",
"call",
"code",
"config",
"dialer_name",
"endpoint",
"event",
"goversion",
"handler",
"instance",
"interval",
"job",
"le",
"listener_name",
"name",
"quantile",
"reason",
"role",
"scrape_job",
"slice",
"version"
]
}
Получение значений меток
Этот эндпоинт возвращает список значений для указанного имени метки:
GET /prometheus/api/v1/label/<label_name>/values
Пример:
Пример запроса для значений метки job
:
$ curl -H "X-Auth-Token: <API-token>" \
https://api.dop.example.com/prometheus/api/v1/label/job/values
Ответ:
{
"status" : "success",
"data" : [
"node",
"prometheus"
]
}
Форматы результатов запросов выражений
Запросы выражений могут возвращать следующие значения в свойстве result
секции данных. Шаблоны <sample_value>
используются для представления числовых значений. Поскольку формат JSON не поддерживает специальные значения с плавающей точкой, такие как NaN
, Inf
и -Inf
, образцы данных передаются как строковые значения в кавычках вместо чисел.
Ключи "histogram"
и "histograms"
появляются только в том случае, если в ответе присутствуют экспериментальные нативные гистограммы. Шаблон <histogram>
поясняется ниже в отдельном разделе.
Range vectors
Range vectors возвращаются как результат типа matrix
. Соответствующее свойство result
имеет следующий формат:
[
{
"metric": { "<label_name>": "<label_value>", ... },
"values": [ [ <unix_time>, "<sample_value>" ], ... ],
"histograms": [ [ <unix_time>, <histogram> ], ... ]
},
...
]
Каждая серия может включать ключ values
, ключ histograms
, или оба. Для каждого временного штампа будет только одна выборка — либо типа float
, либо типа histogram
.
Серии возвращаются отсортированными по метрикам. Функции, такие как sort
и sort_by_label
, не влияют на векторы диапазонов.
Instant vectors
Мгновенные векторы возвращаются как результат типа vector
. Соответствующее свойство result
имеет следующий формат:
[
{
"metric": { "<label_name>": "<label_value>", ... },
"value": [ <unix_time>, "<sample_value>" ],
"histogram": [ <unix_time>, <histogram> ]
},
...
]
Каждая серия может содержать ключ value
или ключ histogram
, но не оба.
Серии не гарантируются в каком-либо определённом порядке, если не была использована функция, такая как sort
или sort_by_label
.
Scalars
Скалярные результаты возвращаются как результат типа scalar
. Соответствующее свойство result
имеет следующий формат:
[ <unix_time>, "<scalar_value>" ]
Строки
Строковые результаты возвращаются как результат типа string
. Соответствующее свойство result
имеет следующий формат:
[ <unix_time>, "<string_value>" ]
Логи
Отправка логов
POST /loki/api/v1/push
Этот эндпоинт используется для отправки логов в Deckhouse Observability Platform. По умолчанию тело POST-запроса должно быть сжато с использованием Snappy Protocol Buffer
сообщением:
Эти POST-запросы требуют HTTP-заголовка Content-Type: application/x-protobuf
.
Альтернативно, если заголовок Content-Type
установлен на application/json
, можно отправить тело POST-запроса в формате JSON:
{
"streams": [
{
"stream": {
"label": "value"
},
"values": [
[ "<Unix Timestamp в наносекундах>", "<лог строка>" ],
[ "<Unix Timestamp в наносекундах>", "<лог строка>" ]
]
}
]
}
Можно установить заголовок запроса Content-Encoding: gzip
для отправки сжатого JSON.
Также можно присоединить структурированные метаданные к каждой строке логов, добавив JSON-объект в конец массива логов. Этот объект не должен содержать вложенные объекты, и должен содержать только строковые ключи и значения. Он должен быть указан сразу после строки лога:
Пример:
"values": [
[ "<Unix Timestamp в наносекундах>", "<лог строка>", {"trace_id": "0242ac120002", "user_id": "superUser123"}]
]
Примеры:
Пример команды cURL для отправки потока с меткой foo=bar2
и одной строкой лога "fizzbuzz"
с использованием кодировки JSON:
curl -H "Content-Type: application/json" \
-H "X-Auth-Token: <API-token>" \
-s -X POST "https://api.dop.example.com/loki/api/v1/push" \
--data-raw '{"streams": [{ "stream": { "foo": "bar2" }, "values": [ [ "1570818238000000000", "fizzbuzz" ] ] }]}'
Просмотр логов
Instant queries
GET /loki/api/v1/query
Этот эндпоинт позволяет выполнять запросы логов для конкретного момента времени. Instant query используются только для запрашивания логов с метриками LogQL и вернут ошибку 400 (Bad Request) в случае использования запроса логов.
Параметры запроса в URL:
query
: Запрос LogQL. Запросы с некорректным синтаксисом LogQL вернут ошибку.limit
: Максимальное количество записей для возврата. По умолчанию — 100. Применяется только для запросов, которые возвращают лог-линии.time
: Время выполнения запроса в формате Unix Timestamp в наносекундах (или другом формате). По умолчанию — текущее время.direction
: Определяет порядок сортировки логов. Поддерживаемые значения:forward
илиbackward
. По умолчанию —backward
.
Формат ответа:
{
"status": "success",
"data": {
"resultType": "vector" | "streams",
"result": [<vector value>] | [<stream value>],
"stats": [<statistics>]
}
}
Где vector value
имеет формат:
{
"metric": {
<label key-value pairs>
},
"value": [
<number: second Unix Timestamp>,
<string: value>
]
}
и stream value
имеет формат:
{
"stream": {
<label key-value pairs>
},
"values": [
[
<string: nanosecond Unix Timestamp>,
<string: log line>
],
...
]
}
Элементы в массиве values
сортируются по времени. Первый элемент — самый свежий при использовании direction=backward
. Самый старый элемент — первый при использовании direction=forward
.
Пример:
curl -G -s -H 'X-Auth-Token: <API-token>' "https://api.dop.example.com/loki/api/v1/query" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' | jq
Ответ:
{
"status": "success",
"data": {
"resultType": "vector",
"result": [
{
"metric": {},
"value": [
1588889221,
"1267.1266666666666"
]
},
{
"metric": {
"level": "warn"
},
"value": [
1588889221,
"37.77166666666667"
]
},
{
"metric": {
"level": "info"
},
"value": [
1588889221,
"37.69"
]
}
],
"stats": {
...
}
}
}
Range query
GET /loki/api/v1/query_range
Этот эндпоинт позволяет запрашивать логи в пределах определенного временного диапазона. Его применяют как к запросам логов, так и к метрическим запросам LogQL.
Параметры запроса в URL:
query
: Запрос LogQL для выполнения.limit
: Максимальное количество возвращаемых записей. По умолчанию равно 100. Применяется только к типам запросов, которые возвращают поток (строки логов).start
: Начальное время запроса в виде Unix Timestamp в наносекундах или другом поддерживаемом формате. По умолчанию — один час назад. Loki возвращает результаты с меткой времени больше или равной этому значению.end
: Конечное время запроса, также в виде Unix Timestamp в наносекундах или другом поддерживаемом формате. По умолчанию — текущее время. Loki возвращает результаты с меткой времени меньше этого значения.since
: Длительность, используемая для вычисления начала относительно конца. Если значениеend
находится в будущем, начальное время вычисляется как эта длительность до текущего момента. Любое заданное значение параметраstart
имеет приоритет надsince
.step
: Шаг разбивки запроса в формате длительности или вещественное число, представляющее количество секунд. Длительность подразумевает строки формата Prometheus, такие как [0-9]+[smhdwy]. Например,5m
означает длительность в 5 минут. По умолчанию — динамическое значение на основеstart
иend
. Применяется к запросам, которые возвращают ответ в виде матрицы.interval
: Возвращает записи не реже, чем указанный интервал, может быть задан в формате длительности или вещественного числа секунд. Работает только для запросов, возвращающих поток. Не путать с параметромstep
, смотрите объяснение ниже.direction
: Определяет порядок сортировки логов. Поддерживаемые значения —forward
(по возрастанию) илиbackward
(по убыванию). По умолчанию -backward
.
Формат ответа:
{
"status": "success",
"data": {
"resultType": "matrix" | "streams",
"result": [<matrix value>] | [<stream value>],
"stats" : [<statistics>]
}
}
Где <matrix value>
имеет формат:
{
"metric": {
<label key-value pairs>
},
"values": [
[
<number: second Unix Timestamp>,
<string: value>
],
...
]
}
и <stream value>
имеет формат:
{
"stream": {
<label key-value pairs>
},
"values": [
[
<string: nanosecond Unix Timestamp>,
<string: log line>
],
...
]
}
Элементы в массиве values
отсортированы по временной метке: если используется параметр direction=backward
, первой идет самая свежая запись, а если forward
— самой старой записью.
Примеры:
curl -G -s -H 'X-Auth-Token: <API-token>' "https://api.dop.example.com/loki/api/v1/query_range" \
--data-urlencode 'query=sum(rate({job="varlogs"}[10m])) by (level)' \
--data-urlencode 'step=300' | jq
Ответ:
{
"status": "success",
"data": {
"resultType": "matrix",
"result": [
{
"metric": {
"level": "info"
},
"values": [
[
1588889221,
"137.95"
],
[
1588889221,
"467.115"
],
[
1588889221,
"658.8516666666667"
]
]
},
{
"metric": {
"level": "warn"
},
"values": [
[
1588889221,
"137.27833333333334"
],
[
1588889221,
"467.69"
],
[
1588889221,
"660.6933333333334"
]
]
}
],
"stats": {
...
}
}
}
Query labels
GET /loki/api/v1/labels
Этот эндпоинт возвращает список известных меток в пределах временного диапазона.
Параметры запроса в URL:
start
: Начальное время запроса как Unix Timestamp в наносекундах. По умолчанию — 6 часов назад.end
: Конечное время, так же в формате Unix Timestamp в наносекундах. По умолчанию — текущее время.since
: Длительность для вычисления начала относительно конца.query
: Селектор потока логов, выбирающий потоки для отображения меток. Пример:{app="myapp", environment="dev"}
Формат ответа:
{
"status": "success",
"data": [
<label string>,
...
]
}
Пример:
curl -G -s -H"X-Auth-Token: <API-token>" "https://api.dop.example.com/loki/api/v1/labels" | jq
Ответ:
{
"status": "success",
"data": [
"foo",
"bar",
"baz"
]
}
Query label values
GET /loki/api/v1/label/<name>/values
Этот эндпоинт возвращает список возможных значений метки <name>
в пределах временного диапазона.
Параметры запроса в URL:
start
: Начальное время.end
: Конечное время.since
: Длительность для вычисления начала относительно конца.query
: Селектор логов для выбора потоков и возвращения значений метки.
Пример:
curl -G -s -H"X-Auth-Token: <API-token>" "https://api.dop.example.com/loki/api/v1/label/foo/values" | jq
Ответ:
{
"status": "success",
"data": [
"cat",
"dog",
"axolotl"
]
}