/api/query

Подзапросы

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

• Запрос метрики - Полное имя метрики предоставляется вместе с необязательным списком тегов. Это оптимизировано для агрегирования нескольких временных рядов в один результат.
• Запрос TSUID - Список одного или нескольких TSUID, которые разделяют общую метрику. Это оптимизировано для извлечения отдельных временных рядов, где агрегирование не требуется.

Запрос может включать более одного подзапроса и любое сочетание двух типов. При отправке запроса через тело содержимого, если предоставляется список TSUID, метрика и теги для данного подзапроса будут проигнорированы.

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

Имя	Тип данных	Обязательно	Описание	Значение по умолчанию	Пример
aggregator	Строка	Обязательно	Имя функции агрегирования для использования. См. /api/aggregators		sum
metric	Строка	Обязательно	Имя метрики, хранящейся в системе		sys.cpu.0
rate	Булево	Необязательно	Преобразовывать ли данные в дельты перед возвратом. Это полезно, если метрика — это непрерывно увеличивающийся счётчик, и вы хотите просмотреть скорость изменения между точками данных.	false	true
rateOptions	Карта	Необязательно	Параметры обработки монотонно возрастающих счётчиков	См. ниже	См. ниже
downsample	Строка	Необязательно	Необязательная функция усреднения для уменьшения количества возвращаемых данных.	См. ниже	5m-avg
tags	Карта	Необязательно	Для детализации до конкретных временных рядов или группировки результатов по тегу, предоставьте одно или несколько значений карты в том же формате, что и строка запроса. Теги преобразуются в фильтры в 2.2. Обратите внимание, что если теги не указаны, все метрики в системе будут агрегированы в результаты. Устарело в 2.2		См. ниже
filters (2.2)	Список	Необязательно	Фильтрует временные ряды, выводимые в результатах. Обратите внимание, что если фильтры не указаны, все временные ряды для заданной метрики будут агрегированы в результаты.		См. ниже
explicitTags (2.3)	Булево	Необязательно	Возвращает ряды, которые содержат только ключи тегов, предоставленные в фильтрах.	false	true

Параметры скорости

При передаче параметров скорости в строке запроса параметры должны быть заключены в фигурные скобки. Например: m=sum:rate{counter,,1000}:if.octets.in. Если вы хотите использовать значения по умолчанию counterMax , но хотите указать resetValue, вы должны добавить две запятые, как в предыдущем примере. Дополнительные поля в объекте rateOptions включают следующее:

Имя	Тип данных	Обязательно	Описание	Значение по умолчанию	Пример
counter	Булево	Необязательно	Являются ли основанные данные монотонно возрастающим счётчиком, который может переполняться	false	true
counterMax	Целое	Необязательно	Положительное целое число, представляющее максимальное значение для счётчика.	Java Long.MaxValue	65535
resetValue	Целое	Необязательно	Необязательное значение, которое, при превышении, заставит агрегатор вернуть 0 вместо рассчитанной скорости. Полезно, когда источники данных часто сбрасываются, чтобы избежать ложных пиков.	0	65000

Усреднение

Спецификации усреднения const, если интервал, единица времени, агрегатор и (с 2.2) необязательная политика заполнения. Формат спецификации усреднения:

<interval><units>-<aggregator>[-<fill policy>]

Например:

1h-sum
30m-avg-nan
24h-max-zero

См. Агрегаторы для списка поддерживаемых политик заполнения.

Фильтры

Нововведение для 2.2, OpenTSDB включает расширенные и подключаемые фильтры для комбинаций ключей и значений тегов. Для списка фильтров, загруженных в TSD, см. /api/config/filters. Для описания встроенных фильтров см. Фильтры. Фильтры могут использоваться как в запросах со строкой запроса, так и в запросах в формате POST. Разрешено несколько фильтров для одного и того же ключа тега, и при обработке они связываются с помощью И, например, если у нас есть два фильтра host=literal_or(web01) и host=literal_or(web02) запрос всегда вернёт пустой результат. Если для одного и того же ключа тега включено два или более фильтров, и один из них включил группировку, а другой — нет, тогда группировка по умолчанию будет true для всех фильтров по этому ключу тега. Поля для запросов POST, относящиеся к фильтрам, включают:

Имя	Тип данных	Обязательно	Описание	Значение по умолчанию	Пример
type	Строка	Обязательно	Имя вызываемого фильтра. См. /api/config/filters		regexp
tagk	Строка	Обязательно	Ключ тега, на котором вызывается фильтр		host
filter	Строка	Обязательно	Выражение фильтра для оценки, зависит от используемого фильтра		web.*.mysite.com
groupBy	Булево	Необязательно	Группировать ли результаты по каждому значению, соответствующему фильтру. По умолчанию все значения, соответствующие фильтру, будут агрегированы в один ряд.	false	true

Для запросов URI тип предшествует выражению фильтра в скобках. Формат: <tagk>=<type>(<filter_expression>). Группируются ли результаты зависит от того, в какой фигурной скобке находится фильтр. Теперь поддерживаются две фигурные скобки на запрос метрики. Первая пара фигурных скобок — это фильтр группировки, а вторая — фильтр без группировки, например {host=wildcard(web*)}{colo=regexp(sjc.*)}. Это указывает на любые метрики, где коло соответствует выражению регулярного выражения "sjc.*" и значение тега host начинается со "web", и результаты группируются по host. Если вы хотите только отфильтровать без группировки, то первая пара фигурных скобок должна быть пустой, например {}{host=wildcard(web*),colo=regexp(sjc.*)}. Это указывает на любые метрики, где colo соответствует выражению регулярного выражения "sjc.*" и значение тега host начинается со "web", и результаты не группируются.

Преобразования фильтров

Значения в запросе POST tags карта и фигурные скобки группировки в запросах URI автоматически преобразуются в фильтры для обеспечения обратной совместимости с существующими системами. Автоматические преобразования включают:

Пример	Описание
<tagk>=*	Фильтр с подстановкой, эффективно гарантирует, что ключ тега присутствует в ряду
<tagk>=value	Буквенный фильтр ИЛИ, чувствительный к регистру
<tagk>=value1|value2|valueN	Буквенный фильтр ИЛИ, чувствительный к регистру
<tagk>=va*	Нечувствительный к регистру фильтр с подстановкой. Звёздочка (*) с любыми другими строками теперь становится сокращением фильтра с подстановкой

Формат строки запроса метрики

Полная спецификация подзапроса строки запроса метрики приведена ниже:

m=<aggregator>:[rate[{counter[,<counter_max>[,<reset_value>]]]}:][<down_sampler>:][explicit_tags:]<metric_name>[{<tag_name1>=<grouping filter>[,...<tag_nameN>=<grouping_filter>]}][{<tag_name1>=<non grouping filter>[,...<tag_nameN>=<non_grouping_filter>]}]

Сначала это может показаться сложным, но вы можете разбить его на компоненты. Если вы когда-нибудь запутаетесь, попробуйте использовать встроенный графический интерфейс для построения графика так, как вы хотите, а затем посмотрите на URL, чтобы увидеть, как отформатирован запрос. Изменения любых полей формы обновят URL (который можно скопировать и вставить, чтобы поделиться с другими пользователями). Примеры см. в Примерах запросов.

Формат строки запроса TSUID

Запросы TSUID проще, чем запросы метрики. Просто передайте список одного или нескольких TSUID в шестнадцатеричном кодировании, разделённых запятыми:

tsuid=<aggregator>:<tsuid1>[,...<tsuidN>]

Примеры запросов со строкой запроса

http://localhost:4242/api/query?start=1h-ago&m=sum:rate:proc.stat.cpu{host=foo,type=idle}
http://localhost:4242/api/query?start=1h-ago&tsuid=sum:000001000002000042,000001000002000043

Пример запроса с содержанием

См. документацию по сериализатору для получения информации о запросе: Сериализаторы HTTP. Следующие примеры относятся к сериализатору JSON по умолчанию.

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0",
      "rate": "true",
      "tags": {
        "host": "*",
        "dc": "lga"
      }
    },
    {
      "aggregator": "sum",
      "tsuids": [
        "000001000002000042",
        "000001000002000043"
        ]
      }
    }
  ]
}

Запрос 2.2 с фильтрами

{
  "start": 1356998400,
  "end": 1356998460,
  "queries": [
    {
      "aggregator": "sum",
      "metric": "sys.cpu.0",
      "rate": "true",
      "filters": [
        {
           "type":"wildcard",
           "tagk":"host",
           "filter":"*",
           "groupBy":true
        },
        {
           "type":"literal_or",
           "tagk":"dc",
           "filter":"lga|lga1|lga2",
           "groupBy":false
        },
      ]
    },
    {
      "aggregator": "sum",
      "tsuids": [
        "000001000002000042",
        "000001000002000043"
        ]
      }
    }
  ]
}

[]

Пример агрегированного ответа по умолчанию

[
  {
    "metric": "tsd.hbase.puts",
    "tags": {},
    "aggregatedTags": [
      "host"
    ],
    "annotations": [
      {
        "tsuid": "00001C0000FB0000FB",
        "description": "Testing Annotations",
        "notes": "These would be details about the event, the description is just a summary",
        "custom": {
          "owner": "jdoe",
          "dept": "ops"
        },
        "endTime": 0,
        "startTime": 1365966062
      }
    ],
    "globalAnnotations": [
      {
        "description": "Notice",
        "notes": "DAL was down during this period",
        "custom": null,
        "endTime": 1365966164,
        "startTime": 1365966064
      }
    ],
    "tsuids": [
      "0023E3000002000008000006000001"
    ],
    "dps": {
      "1365966001": 25595461080,
      "1365966061": 25595542522,
      "1365966062": 25595543979,
...
      "1365973801": 25717417859
    }
  }
]

Пример агрегированного ответа в формате массива

[
  {
    "metric": "tsd.hbase.puts",
    "tags": {},
    "aggregatedTags": [
      "host"
    ],
    "dps": [
      [
        1365966001,
        25595461080
      ],
      [
        1365966061,
        25595542522
      ],
...
      [
        1365974221,
        25722266376
      ]
    ]
  }
]

Пример ответа с несколькими наборами

В приведенном примере работали два TSD, и запрос был: http://localhost:4242/api/query?start=1h-ago&m=sum:tsd.hbase.puts{host=*}. Это возвращает два явных временных ряда.

[
  {
    "metric": "tsd.hbase.puts",
    "tags": {
      "host": "tsdb-1.mysite.com"
    },
    "aggregatedTags": [],
    "dps": {
      "1365966001": 3758788892,
      "1365966061": 3758804070,
...
      "1365974281": 3778141673
    }
  },
  {
    "metric": "tsd.hbase.puts",
    "tags": {
      "host": "tsdb-2.mysite.com"
    },
    "aggregatedTags": [],
    "dps": {
      "1365966001": 3902179270,
      "1365966062": 3902197769,
...
      "1365974281": 3922266478
    }
  }
]

Пример с отображением сводки и запросом

[
  {
    "metric": "tsd.hbase.puts",
    "tags": {},
    "aggregatedTags": [
      "host"
    ],
    "query": {
      "aggregator": "sum",
      "metric": "tsd.hbase.puts",
      "tsuids": null,
      "downsample": null,
      "rate": true,
      "explicitTags": false,
      "filters": [
        {
          "tagk": "host",
          "filter": "*",
          "group_by": true,
          "type": "wildcard"
        }
      ],
      "rateOptions": null,
      "tags": { }
    },
    "dps": {
      "1365966001": 25595461080,
      "1365966061": 25595542522,
      "1365966062": 25595543979,
...
      "1365973801": 25717417859
    }
  },
  {
    "statsSummary": {
      "datapoints": 0,
      "rawDatapoints": 56,
      "aggregationTime": 0,
      "serializationTime": 20,
      "storageTime": 6,
      "timeTotal": 26
    }
  }
]