Prometheus Learning Series (23) PromQL HTTP API

монитор

на сервере Прометей/api/v1Текущий стабильный HTTP API доступен по адресу. Любые неразрывные дополнения будут добавлены под этой конечной точкой.

Обзор формата

Возвращает API в формате JSON. Возвращаемое значение для каждого успешного запроса2xxкодировка для начала.

Недопустимый запрос, полученный для обработки API, возвращает объект ошибки JSON со следующим кодом ошибки:

  • 400 Bad Request. Когда параметр неправильный или отсутствует.
  • 422 Unprocessable Entity. Когда выражение не может быть выполнено.
  • 503 Service Unavailable. Когда запрос истекает или прерывается.

Для ошибок, которые происходят до достижения конечной точки API, другие не2xxкод.

Массив предупреждений может быть возвращен, если есть ошибка, не препятствующая выполнению запроса. Все успешно собранные данные будут возвращены в поле данных.

Формат конверта ответа JSON выглядит следующим образом:

{
  "status": "success" | "error",
  "data": <data>,

  // Only set if status is "error". The data field may still hold
  // additional data.
  "errorType": "<string>",
  "error": "<string>",

  // Only if there were warnings while executing the request.
  // There will still be data in the data field.
  "warnings": ["<string>"]
}

Ввод временных меток может бытьRFC3339Предоставляется формат, который также может быть предоставлен для временных меток Unix в секундах с необязательным числом десятичных знаков для точности до доли секунды. Выходные временные метки всегда представлены в виде временных меток Unix в секундах.

возможно[]Имя конечного параметра запроса.

<series_selector>Заполнители относятся к селекторам временных рядов Prometheus, таким какhttp_requests_totalилиhttp_requests_total{method =〜"(GET|POST)"}, который должен быть закодирован в URL.

<duration>заполнители относятся к[0-9]+[smhdwy]Строка длительности Prometheus в форме. Например,5mОтносится к продолжительности 5 минут.

<bool>ссылка-заполнитель логическое значение (строкаtrueиfalse).

2. Выражение запроса

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

2.1 Мгновенные запросы

Следующие конечные точки оценивают немедленные запросы в один момент времени:

GET /api/v1/query

Параметры URL-запроса:

  • query=<string>: строка запроса выражения Prometheus.
  • time=<rfc3339 | uninx_timestamp>: Отметка времени выполнения, необязательно.
  • timeout=<duration>: настройка тайм-аута выполнения, необязательно, по умолчанию устанавливается-query.timeoutустановка флага

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

результат этого запросаdataРазделы имеют следующий формат:

{
 "resultType": "matrix" | "vector" | "scalar" | "string",
 "result": <value>
}

<value>это данные результата запроса, которые зависят от этогоresultTypeформат см.Формат результата запроса выражения> .

Следующий пример выполняется в данный момент2015-07-01T20:10:51.781Zизupвыражение:

$ curl 'http://localhost:9090/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" ]
         }
    ]
 }
}
2.2 Запрос диапазона

Следующие конечные точки оценивают запросы выражений в течение определенного периода времени:

GET /api/v1/query_range

Параметры URL-запроса

  • query=<string>: строка запроса выражения Prometheus.
  • start=<rfc3339 | unix_timestamp>: Отметка времени начала.
  • end=<rfc3339 | unix_timestamp>: метка времени окончания.
  • step=<duration>: Шаги разрешения запроса или секунды с плавающей запятой в формате длительности.
  • timeout=<duration>: Время ожидания оценки. по желанию. По умолчанию-query.timeoutЗначение флага и связанное им.

Часть данных результата запроса имеет следующий формат:

{
    "resultType": "matrix",
    "result": <value>
}

за<value>Формат заполнителей см.Формат результата вектора диапазона.

В следующем примере выражение оценивается в 30-секундном диапазоне с разрешением запроса 15 секунд.

$ curl 'http://localhost:9090/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" ]
            ]
         }
      ]
   }
}
3. Запрос метаданных
3.1 Найдите список метрик с помощью сопоставления тегов

Следующая конечная точка возвращает список временных рядов, соответствующих определенному набору меток.

GET /api/v1/series

Параметры URL-запроса:

  • match[]=<series_selector>: селектор — это серия_селектор. Количество параметров должно быть больше или равно 1.
  • start=<rfc3339 | unix_timestamp>: Отметка времени начала.
  • end=<rfc3339 | unix_timestamp>: метка времени окончания.

результат запросаdataРаздел содержит список объектов, содержащих пары имя/значение метки, которые идентифицируют каждую серию.

В следующем примере возвращаются данные временного ряда, селекторupилиprocess_start_time_seconds{job="prometheus"}

$ curl -g 'http://localhost:9090/api/v1/series?match[]=up&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"
      }
   ]
}
3.2 Значение тега запроса

Следующая конечная точка возвращает список имен меток:

GET /api/v1/label/<label_name>/values

JSON-ответdatasection представляет собой список имен строковых меток.

Вот пример.

$ curl http://localhost:9090/api/v1/label/job/values
{
   "status" : "success",
   "data" : [
      "node",
      "prometheus"
   ]
}
3.3 Значение тега запроса

Следующая конечная точка возвращает список значений тега для предоставленного имени тега:

GET /api/v1/label/<label_name>/values

JSON-ответdatasection представляет собой список значений строковых тегов.

Этот пример запрашивает все значения тега для тега задания:

$ curl http://localhost:9090/api/v1/label/job/values
{
   "status" : "success",
   "data" : [
      "node",
      "prometheus"
   ]
}
4. Формат результата запроса выражения

Запросы-выражения могут бытьdataчастьresultВ свойстве возвращаются следующие значения ответа.<sample_value>Заполнители представляют собой числовые образцы значений. JSON не поддерживает специальные значения с плавающей запятой, такие какNaN,Infи-Inf, поэтому значение образца будет передано в виде строки JSON в кавычках, а не в виде необработанного числа.

4.1 Вектор дальности

Тип результата, возвращаемый вектором диапазона, представляет собойmatrixматрица. Результат, возвращаемый ниже,resultЧасть формата данных:

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "values": [ [ <unix_time>, "<sample_value>" ], ... ]
  },
  ...
]
4.2 Мгновенные векторы

мгновенный векторresultтипvector. Нижеresultчасть формата данных

[
  {
    "metric": { "<label_name>": "<label_value>", ... },
    "value": [ <unix_time>, "<sample_value>" ]
  },
  ...
]
4.3 Скаляры

Скалярный запрос возвращаетresultтипscalar. НижеresultЧасть формата данных:

[ <unix_time>, "<scalar_value>" ]

4.4 Струны

нитьresultтипstring. НижеresultЧасть формата данных:

[ <unix_time>, "<string_value>" ]

5. Цели

Следующие конечные точки возвращают обзор текущего состояния обнаружения цели Prometheus:

GET /api/v1/targets

И активная цель, и цель удаления являются частью ответа.labelsПредставляет набор меток после перемаркировки.discoveredLabelsПредставляет неизмененную метку, полученную во время обнаружения службы до того, как произошло изменение метки.

$ curl http://localhost:9090/api/v1/targets
{
  "status": "success",
  "data": {
    "activeTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9090",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "prometheus"
        },
        "labels": {
          "instance": "127.0.0.1:9090",
          "job": "prometheus"
        },
        "scrapeUrl": "http://127.0.0.1:9090/metrics",
        "lastError": "",
        "lastScrape": "2017-01-17T15:07:44.723715405+01:00",
        "health": "up"
      }
    ],
    "droppedTargets": [
      {
        "discoveredLabels": {
          "__address__": "127.0.0.1:9100",
          "__metrics_path__": "/metrics",
          "__scheme__": "http",
          "job": "node"
        },
      }
    ]
  }
}
6. Правила

/rulesКонечная точка API возвращает список загруженных в данный момент правил оповещения и ведения журнала. Кроме того, он возвращает текущие активные предупреждения, инициированные экземпляром Prometheus, для каждого правила предупреждений.

так как/rulesКонечная точка довольно новая и не имеет таких же гарантий стабильности, как общий API v1.

GET /api/v1/rules

$ curl http://localhost:9090/api/v1/rules

{
    "data": {
        "groups": [
            {
                "rules": [
                    {
                        "alerts": [
                            {
                                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                                "annotations": {
                                    "summary": "High request latency"
                                },
                                "labels": {
                                    "alertname": "HighRequestLatency",
                                    "severity": "page"
                                },
                                "state": "firing",
                                "value": 1
                            }
                        ],
                        "annotations": {
                            "summary": "High request latency"
                        },
                        "duration": 600,
                        "health": "ok",
                        "labels": {
                            "severity": "page"
                        },
                        "name": "HighRequestLatency",
                        "query": "job:request_latency_seconds:mean5m{job=\"myjob\"} > 0.5",
                        "type": "alerting"
                    },
                    {
                        "health": "ok",
                        "name": "job:http_inprogress_requests:sum",
                        "query": "sum(http_inprogress_requests) by (job)",
                        "type": "recording"
                    }
                ],
                "file": "/rules.yaml",
                "interval": 60,
                "name": "example"
            }
        ]
    },
    "status": "success"
}
Семь, тревожный сигнал

/alertsКонечная точка возвращает список всех активных оповещений.

так как/alertsКонечная точка довольно новая и не имеет таких же гарантий стабильности, как общий API v1.

GET /api/v1/alerts

$ curl http://localhost:9090/api/v1/alerts

{
    "data": {
        "alerts": [
            {
                "activeAt": "2018-07-04T20:27:12.60602144+02:00",
                "annotations": {},
                "labels": {
                    "alertname": "my-alert"
                },
                "state": "firing",
                "value": 1
            }
        ]
    },
    "status": "success"
}
8. Запросите метаданные цели

Следующие конечные точки возвращают метаданные о метриках, которые собирает цель. Это экспериментально и может измениться в будущем.

GET /api/v1/targets/metadata

Параметры URL-запроса:

  • match_target=<label_selectors>: Селектор тегов, который соответствует цели по набору тегов. Если оставить пустым, выбираются все цели.
  • metric=<string>: имя метрики, используемое для извлечения метаданных. Если оставить пустым, извлекаются все метаданные метрик.
  • limit=<number>: максимальное количество целей для сопоставления.

результат запросаdataРаздел содержит список объектов, содержащих метаданные метрик и наборы целевых меток.

Следующий пример возвращается из первых двух целейgo_goroutinesВсе записи метаданных для метрики, помеченныеjob ="prometheus".

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'metric=go_goroutines' \
    --data-urlencode 'match_target={job="prometheus"}' \
    --data-urlencode 'limit=2'
{
  "status": "success",
  "data": [
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9091",
        "job": "prometheus"
      },
      "type": "gauge",
      "help": "Number of goroutines that currently exist.",
      "unit": ""
    }
  ]
}

В следующем примере возвращает этикеткуinstance="127.0.0.1:9090"Метаданные для всех показателей для всех целей.

curl -G http://localhost:9091/api/v1/targets/metadata \
    --data-urlencode 'match_target={instance="127.0.0.1:9090"}'
{
  "status": "success",
  "data": [
    // ...
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_treecache_zookeeper_failures_total",
      "type": "counter",
      "help": "The total number of ZooKeeper failures.",
      "unit": ""
    },
    {
      "target": {
        "instance": "127.0.0.1:9090",
        "job": "prometheus"
      },
      "metric": "prometheus_tsdb_reloads_total",
      "type": "counter",
      "help": "Number of times the database reloaded block data from disk.",
      "unit": ""
    },
    // ...
  ]
}
9. Диспетчер предупреждений Altmanagers

Следующие конечные точки возвращают обзор текущего состояния, обнаруженного менеджером предупреждений Prometheus:

GET /api/v1/alertmanagers

Как активные, так и сброшенные Alertmanager являются частью ответа.

$ curl http://localhost:9090/api/v1/alertmanagers
{
  "status": "success",
  "data": {
    "activeAlertmanagers": [
      {
        "url": "http://127.0.0.1:9090/api/v1/alerts"
      }
    ],
    "droppedAlertmanagers": [
      {
        "url": "http://127.0.0.1:9093/api/v1/alerts"
      }
    ]
  }
}
10. Статус

Следующая конечная точка состояния показывает текущую конфигурацию Prometheus.

10.1 Конфигурация конфигурации

Следующие конечные точки возвращают загруженный в данный момент файл конфигурации:

GET /api/v1/status/config

Конфигурация возвращается в виде файла дампа YAML. Из-за ограничений библиотеки YAML комментарии YAML не включаются.

$ curl http://localhost:9090/api/v1/status/config
{
  "status": "success",
  "data": {
    "yaml": "<content of the loaded config file in YAML>",
  }
}
10.2 Флаги

Следующие конечные точки возвращают значения флагов, настроенные Prometheus:

GET /api/v1/status/flags

Все значения отображаются как «строки».

$ curl http://localhost:9090/api/v1/status/flags
{
  "status": "success",
  "data": {
    "alertmanager.notification-queue-capacity": "10000",
    "alertmanager.timeout": "10s",
    "log.level": "info",
    "query.lookback-delta": "5m",
    "query.max-concurrency": "20",
    ...
  }
}

Новое в версии 2.2.

Одиннадцать, API администрирования TSDB, API управления TSDB

Это API-интерфейсы, которые предоставляют функциональные возможности базы данных для опытных пользователей. если не установлено--web.enable-admin-api, иначе эти API не будут включены.

Мы также предоставляем gRPC API, определение которого можно найти здесь. Это экспериментально и может измениться в будущем.

11.1 Снимки

Моментальный снимок создаст моментальный снимок всех текущих данных в каталоге данных TSDB вsnapshots/<datetime>-<rand>и возвращает этот каталог в качестве ответа. Он может дополнительно пропускать данные снимка, которые существуют только в блоках заголовков, но еще не сжаты на диск.

POST /api/v1/admin/tsdb/snapshot?skip_head=

$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/snapshot
{
  "status": "success",
  "data": {
    "name": "20171210T211224Z-2be650b6d019eb54"
  }
}

Снимок уже существует<data-dir>/snapshots/20171210T211224Z-2be650b6d019eb54Новое в версии 2.1.

11.2 Удаление последовательности

DeleteSeries удаляет данные для выбранной серии в пределах временного диапазона. Фактические данные все еще существуют на диске и очищаются при будущих уплотнениях или могут быть очищены явным образом путем нажатия на конечную точку Clean Tombstones.

Возвращает в случае успеха204.

POST /api/v1/admin/tsdb/delete_series

Параметры URL-запроса:

  • match[]=<series_selector>: выберите параметр сопоставления повторяющихся меток серии, который необходимо удалить. должен предоставить хотя бы одинmatch[]параметр.
  • start= <rfc3339 | unix_timestamp>: Отметка времени начала. Необязательно, по умолчанию используется кратчайшее возможное время.
  • end= <rfc3339 | unix_timestamp>: метка времени окончания. Необязательно, по умолчанию используется максимально возможное время.

Отсутствие упоминания времени начала и окончания очистит базу данных от всех данных для соответствующих серий.

пример:

$ curl -X POST \
  -g 'http://localhost:9090/api/v1/admin/tsdb/delete_series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'

v2.1 новый контент

11.3 CleanTombstones

CleanTombstones удаляет удаленные данные с диска и очищает существующие надгробия. Это можно использовать после удаления серии, чтобы освободить место.

Возвращает в случае успеха204.

POST /api/v1/admin/tsdb/clean_tombstones

Это не требует никаких параметров или тела.

$ curl -XPOST http://localhost:9090/api/v1/admin/tsdb/clean_tombstones

Новое в версии 2.1.

12. Ссылки

Адрес официального сайта Прометея:prometheus.io/Мой гитхаб:GitHub.com/хорошо это/лжец…

Категории