Модуль доступен только в 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"
  ]
}