/api/query/exp

"time"

Раздел "time" обязателен и представляет собой один JSON-объект. Это влияет на временной диапазон и необязательные сокращения для всех запрашиваемых метрик.

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
start	Целое число	Обязательно	Начальное время для запроса. Может быть относительным, абсолютным в читаемом формате или абсолютным значением эпохи Unix.		1h-ago, 2015/05/05-00:00:00
aggregator	Строка	Обязательно	Глобальная функция агрегирования для всех метрик. Она может быть переопределена для каждой метрики.		sum
end	Целое число	Необязательно	Конечное время для запроса. Если не указано, конечное время — сейчас.	now	1h-ago, 2015/05/05-00:00:00
downsampler	Объект	Необязательно	Уменьшает количество возвращаемых точек данных. Формат определен ниже	None	См. ниже
rate	Булево	Необязательно	Вычислять ли все метрики как скорости, т.е. значение за секунду. Это вычисляется перед выражениями.	false	true

Например:

"time":{ "start":"1h-ago", "end":"10m-ago", "downsampler":{"interval":"15m","aggregator":"max"}

Downsampler

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
interval	Строка	Обязательно	Интервал усреднения, т.е. какой временной интервал использовать для объединения исходных значений. Формат <#><unit>, например 15m		1h
aggregator	Строка	Обязательно	Функция агрегирования для уменьшения количества точек данных		avg
fillPolicy	Объект	Необязательно	Политика для заполнения пустых интервалов, в которых отсутствуют точки данных	None	См. ниже

Политики заполнения

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

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
policy	Строка	Обязательно	Имя используемой политики. Значения указаны в таблице ниже		zero
value	Двойное	Необязательно	Для скалярных заполнений, необязательное значение, которое можно использовать при подстановке	NaN	42

Имя	Описание
nan	Генерирует NaN, если все значения в функции агрегирования были NaN или «пропущенными». Для агрегаторов NaN рассматриваются как «значения-маяки», из-за которых функция пропускает значения. Обратите внимание, что если ряд генерирует NaN в выражении, NaN становится заразным и приводит к тому, что результат этого выражения становится NaN. При сериализации NaN будет сгенерирован.
null	Генерирует Null во время сериализации. Во время вычислений значения обрабатываются как NaN.
zero	Генерирует ноль, когда значение отсутствует
scalar	Генерирует пользовательское значение, когда отсутствует точка данных. Необходимо указать значение с помощью value. Значение может быть целым или с плавающей точкой.

Обратите внимание, что при попытке предоставить несовместимое с типом значение запрос выбросит исключение. Например, предоставление значения с NaN, которое не является NaN, вызовет ошибку.

Например:

{"policy":"scalar","value":"1"}

"filters"

Фильтры предназначены для выбора различных временных рядов на основе ключей и значений тегов. Сейчас необходимо указать хотя бы один фильтр (пока) с хотя бы одной заданной функцией агрегирования. Поля включают:

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
id	Строка	Обязательно	Уникальный идентификатор фильтра. Не может совпадать с идентификатором метрики или выражения		f1
tags	Массив	Необязательно	Список фильтров по значениям тегов	None	См. ниже

Например:

"filters":[
  "id":"f1",
  "tags":[
  {
    "type":"wildcard",
    "tagk":"host",
    "filter":"*",
    "groupBy":true
  },
  {
    "type":"literal_or",
    "tagk":"colo",
    "filter":"lga",
    "groupBy":false
  }
   ]
  ]

Поля фильтра

В поле "tags" может быть один или несколько фильтров. Список фильтров можно найти по адресу /api/config/filters.

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

"metrics"

Список метрик определяет, какие метрики включаются в выражение. Должна быть хотя бы одна метрика.

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
id	Строка	Обязательно	Уникальный идентификатор метрики. ДОЛЖЕН быть простой строкой, без знаков препинания или пробелов		cpunice
filter	Строка	Обязательно	Фильтр, используемый при получении этой метрики. Должен совпадать с фильтром в массиве filters		f1
metric	Строка	Обязательно	Имя метрики в OpenTSDB		system.cpu.nice
aggregator	Строка	Необязательно	Необязательная функция агрегирования для перегрузки глобальной функции в time только для этой метрики	time's aggregator	count
fillPolicy	Объект	Необязательно	Если усреднение не используется, это поле может быть включено, чтобы определить, что отображать в вычислениях. Оно также переопределит политику заполнения при усреднении	zero fill	См. выше

Например:

{"id":"cpunice", "filter":"f1", "metric":"system.cpu.nice"}

"expressions"

Список из одного или нескольких выражений над метриками. Переменные в выражении ДОЛЖНЫ ссылаться на поле ID метрики или поле ID выражения. Вложенные выражения поддерживаются, но исключения будут выброшены, если обнаружена ссылка на себя или циклическая зависимость. На данный момент поддерживаются только базовые операции, такие как сложение, вычитание, умножение, деление, модуль.

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
id	Строка	Обязательно	Уникальный идентификатор выражения		cpubusy
expr	Строка	Обязательно	Выражение для выполнения		a + b / 1024
join	Объект	Необязательно	Операция объединения или "join" для выполнения над сериями по наборам.	union	См. ниже
fillPolicy	Объект	Необязательно	Необязательная политика заполнения для выражения, когда оно используется вложенным выражением и не имеет значения	NaN	См. выше

Например:

{
  "id": "cpubusy",
  "expr": "(((a + b + c + d + e + f + g) - g) / (a + b + c + d + e + f + g)) * 100",
  "join": {
    "operator": "intersection",
    "useQueryTags": true,
    "includeAggTags": false
  }
}

Объединения (Joins)

Объект объединения управляет тем, как различные временные ряды для заданной метрики объединяются в рамках выражения. На данный момент поддерживаются две основные операции: операторы объединения (union) и пересечения (intersection). Дополнительные флаги контролируют поведение объединения.

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
operator	Строка	Обязательно	Оператор для использования, либо объединение (union), либо пересечение (intersection)		intersection
useQueryTags	Булево	Необязательно	Использовать только те метки, которые явно определены в фильтрах при вычислении ключей объединения	false	true
includeAggTags	Булево	Необязательно	Включать ли ключи меток, которые были агрегированы из серии в ключ объединения	true	false

"outputs"

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

Имя	Тип данных	Обязательно	Описание	По умолчанию	Пример
id	Строка	Обязательно	Идентификатор метрики или выражения		e
alias	Строка	Необязательно	Необязательное описательное имя для рядов		Загрузка системы

Например:

{"id":"e", "alias":"System Busy"}

Полный пример

{
   "time": {
     "start": "1y-ago",
     "aggregator":"sum"
   },
   "filters": [
     {
       "tags": [
         {
           "type": "wildcard",
           "tagk": "host",
           "filter": "web*",
           "groupBy": true
         }
       ],
       "id": "f1"
     }
   ],
   "metrics": [
     {
       "id": "a",
       "metric": "sys.cpu.user",
       "filter": "f1",
       "fillPolicy":{"policy":"nan"}
     },
     {
       "id": "b",
       "metric": "sys.cpu.iowait",
       "filter": "f1",
       "fillPolicy":{"policy":"nan"}
     }
   ],
   "expressions": [
     {
       "id": "e",
       "expr": "a + b"
     },
     {
     "id":"e2",
     "expr": "e * 2"
     },
     {
     "id":"e3",
     "expr": "e2 * 2"
     },
     {
     "id":"e4",
     "expr": "e3 * 2"
     },
     {
     "id":"e5",
     "expr": "e4 + e2"
     }
  ],
  "outputs":[
    {"id":"e5", "alias":"Mega expression"},
    {"id":"a", "alias":"CPU User"}
  ]
 }

Примеры ответов

{
  "outputs": [
    {
      "id": "Mega expression",
      "dps": [
        [
          1431561600000,
          1010,
          1030
        ],
        [
          1431561660000,
          "NaN",
          "NaN"
        ],
        [
          1431561720000,
          "NaN",
          "NaN"
        ],
        [
          1431561780000,
          1120,
          1140
        ]
      ],
      "dpsMeta": {
        "firstTimestamp": 1431561600000,
        "lastTimestamp": 1431561780000,
        "setCount": 4,
        "series": 2
      },
      "meta": [
        {
          "index": 0,
          "metrics": [
            "timestamp"
          ]
        },
        {
          "index": 1,
          "metrics": [
            "sys.cpu",
            "sys.iowait"
          ],
          "commonTags": {
            "host": "web01"
          },
          "aggregatedTags": []
        },
        {
          "index": 2,
          "metrics": [
            "sys.cpu",
            "sys.iowait"
          ],
          "commonTags": {
            "host": "web02"
          },
          "aggregatedTags": []
        }
      ]
    },
    {
      "id": "sys.cpu",
      "dps": [
        [
          1431561600000,
          1,
          2
        ],
        [
          1431561660000,
          3,
          0
        ],
        [
          1431561720000,
          5,
          0
        ],
        [
          1431561780000,
          7,
          8
        ]
      ],
      "dpsMeta": {
        "firstTimestamp": 1431561600000,
        "lastTimestamp": 1431561780000,
        "setCount": 4,
        "series": 2
      },
      "meta": [
        {
          "index": 0,
          "metrics": [
            "timestamp"
          ]
        },
        {
          "index": 1,
          "metrics": [
            "sys.cpu"
          ],
          "commonTags": {
            "host": "web01"
          },
          "aggregatedTags": []
        },
        {
          "index": 2,
          "metrics": [
            "sys.cpu"
          ],
          "commonTags": {
            "host": "web02"
          },
          "aggregatedTags": []
        }
      ]
    }
  ],
  "statsSummary": {
    "datapoints": 0,
    "rawDatapoints": 0,
    "aggregationTime": 0,
    "serializationTime": 33,
    "storageTime": 77,
    "timeTotal": 148.63
  },
  "query": {
    "name": null,
    "time": {
      "start": "1y-ago",
      "end": null,
      "timezone": null,
      "downsampler": null,
      "aggregator": "sum"
    },
    "filters": [
      {
        "id": "f1",
        "tags": [
          {
            "tagk": "host",
            "filter": "web*",
            "group_by": true,
            "type": "wildcard"
          }
        ]
      }
    ],
    "metrics": [
      {
        "metric": "sys.cpu",
        "id": "a",
        "filter": "f1",
        "aggregator": null,
        "fillPolicy": {
          "policy": "nan",
          "value": "NaN"
        },
        "timeOffset": null
      },
      {
        "metric": "sys.iowait",
        "id": "b",
        "filter": "f1",
        "aggregator": null,
        "fillPolicy": {
          "policy": "nan",
          "value": "NaN"
        },
        "timeOffset": null
      }
    ],
    "expressions": [
      {
        "id": "e",
        "expr": "a + b"
      },
      {
        "id": "e2",
        "expr": "e * 2"
      },
      {
        "id": "e3",
        "expr": "e2 * 2"
      },
      {
        "id": "e4",
        "expr": "e3 * 2"
      },
      {
        "id": "e5",
        "expr": "e4 + e2"
      }
    ],
    "outputs": [
      {
        "id": "e5",
        "alias": "Woot!"
      },
      {
        "id": "a",
        "alias": "Woot!2"
      }
    ]
   }
}