[Документация Yandex Cloud](../../index.md) > [Monium](../index.md) > Концепции > Язык запросов

# Язык запросов в Monium

Monium использует единый язык запросов для поиска и фильтрации данных телеметрии: метрик, логов и трейсов. С помощью языка запросов можно строить выражения-селекторы, применять функции для преобразования метрик и ссылаться на результаты других запросов как на переменные.

Описание модели данных, включая обязательные атрибуты, метки и метаинформацию, — в разделе [Модель данных в Monium](data-model.md). Объекты конфигурации (проект, кластер, сервис), которые используются в запросах, — в разделе [Конфигурация объектов Monium](configuration-model.md).

## Запросы {#queries}

Запрос — произвольное выражение на языке запросов. Результат выполнения запроса зависит от типа данных:

* Метрики — линия или набор линий.
* Логи — строка или набор строк лога.
* Трейсы (спаны) — набор операций или цепочек операций, которые выполняет распределенное приложение.

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

Запрос состоит из ключа, операции сравнения и значения:

```
{ <key>="<value>", <key>="<value>", ... }
```

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

Помимо поиска по выражению в строке запроса, можно выполнять выборку метрик при помощи [функций](querying-functions.md).

### Типы данных {#data-types}

Язык запросов поддерживает следующие типы данных:

* **Строка** (string) — для всех типов телеметрии.

   Любое литеральное выражение в кавычках (одинарных или двойных) будет представлено как строка.

* **Вещественное число** (scalar) — для метрик и логов.

   Вещественное число с плавающей точкой двойной точности по [стандарту IEEE 754](https://ru.wikipedia.org/wiki/IEEE_754-2008). Для метрик тип данных включает специальное значение `NaN`, для логов — не включает.

   Примеры: `101`, `75.3`, `20G`, `1E-3`.

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

  * `k` — 10^3^;
  * `M` — 10^6^;
  * `G` — 10^9^;
  * `T` — 10^12^;
  * `P` — 10^15^;
  * `E` — 10^18^.

* **Длительность** (duration) — для метрик, трейсов и спанов.

   Значения должны быть в формате `1s`, `10ms`, `150us`, `2m`, `6h` без кавычек.

* **Набор временных рядов** (timeseries_vector) — для метрик.

   Пример объекта типа `timeseries_vector`. Следующее выражение вернет вектор метрик с различными значениями метки `host`:

    ```json
    {service='__compute__', host='*', name='exceptionCount'}
    ```

* **Логический тип** (bool) — для метрик, может принимать значения `true` или `false`.

### Операции в строке запроса {#operations}

* Строки (`string`).

  * `=` и  `!=` — равенство и неравенство. Поддерживаются [glob-выражения](https://ru.wikipedia.org/wiki/Шаблон_поиска) с символами `* ? |`. Символы `[ ]` не поддерживаются.

  * `=~` и `!~` — регулярное выражение в формате [re2](https://github.com/google/re2/wiki/Syntax).

  * `==` и `!==` — строгое равенство и неравенство. Glob-выражения и регулярные выражения будут интерпретированы как обычные символы.

* Длительность (`duration`) — применяется для значений `trace.duration` и `span.duration`.
  * Поддерживаются операции сравнения `> < >= <=`. 
  * Значения должны быть в формате `1s`, `10ms`, `150us`, `2m`, `6h` без кавычек.


### Выражения для фильтрации данных {#expressions}

Язык запросов используется для описания фильтров по данным телеметрии и имеет общие конструкции для разных видов данных (метрик, логов, трейсов). Также есть отличия, обусловленные особенностями модели данных для каждого вида.

Поля верхнего уровня (например, `message`, `level`) рассматриваются как метки. Селектор состоит из имени метки, оператора и выражения, описывающего множество значений меток. Условия внутри селектора объединяются по AND.

#### Операторы для всех типов телеметрии {#operators}

| Вид селектора | Описание | Примеры |
|-|-|-|
| `label="<value>"`   | Возвращает все элементы телеметрии (логи, метрики, трейсы), у которых есть метка `label` со значением, совпадающим с `value`. В значении поддерживаются [glob-выражения](https://ru.wikipedia.org/wiki/Шаблон_поиска) (только символы `*`, `?` и `\|`, символы `[` и `]` не поддерживаются). | `host="vla"` – вернет элементы, у которых значение метки `host` равно `vla`.<br/><br/>`host="*"` – вернет элементы, у которых есть метка `host`.<br/><br/>`host="sas-*"` – вернет элементы, у которых значение метки `host` начинается с префикса `sas-`.<br/><br/>`host="sas-?00"` – вернет элементы со значениями метки `host`, равными `sas-100`, `sas-200` и т. д.<br/><br/>`host="sas*\|vla*"` — вернет элементы, у которых значение метки `host` начинается с префиксов `sas` или `vla`. |
| `label="-"` | Возвращает все элементы, у которых отсутствует указанная метка. Применимо: логи, метрики, трейсы. | `host="-"` – вернет элементы без метки `host`.<br/><br/>`host="-\|myhost"` – вернет элементы без метки `host` или со значением метки `host`, равным `myhost`. |
| `label!="<value>"` | Противоположность селектору `label="<value>"`. Применимо: логи, метрики, трейсы. | `host!="myhost-*"` – вернет элементы, у которых метка `host` отсутствует или ее значение не начинается с префикса `myhost-`. |
| `label=="<value>"`  | Возвращает элементы, у которых значение метки `label` точно совпадает со значением `<value>`, без поддержки `glob`. Применимо: логи, метрики, трейсы. | `host=="myhost"` – вернет элементы, у которых значение метки `host` совпадает со строкой `myhost`.<br/><br/>`host=="*"` — вернет элементы, у которых значение метки `host` содержит буквальный символ `*`. |
| `label!=="<value>"` | Противоположность селектору `label=="<value>"`. Применимо: логи, метрики, трейсы. | `host!=="myhost"` — вернет элементы, у которых отсутствует метка `host` или ее значение не совпадает со строкой `myhost`. |
| `message=*"<substring>"` или `meta.key=*"<substring>"` | Возвращает элементы, у которых значение метки содержит подстроку `<substring>` без учета регистра (`<substring>` может быть `glob`). Применимость: `message` — только логи; `meta.key` — логи, метрики, трейсы (если существует метка `meta.key`). | `message=*"request"` — вернет логи с `message`, равным `Failed search request`, `Request cancelled` и т. д.<br/><br/> `meta.error=*"failed*request"` — вернет элементы, где `meta.error` равен `Failed to make a request`, `Reader failed to retrieve data from a request` и т. д. |
| `message!=*"<substring>"` или `meta.key!=*"<substring>"` | Оператор, обратный `=*`. Применимость: `message` — только логи; `meta.key` — логи, метрики, трейсы (если существует метка `meta.key`). | |
| `label=~"<regex>"` | Возвращает элементы, у которых значение метки `label` удовлетворяет регулярному выражению `<regex>` на языке [re2](https://github.com/google/re2/wiki/Syntax). Применимо: логи, метрики, трейсы. | |
| `label!~"<regex>"` | Противоположность селектору `label=~"<regex>"`. Применимо: логи, метрики, трейсы. | |
| `label>300`         | Возвращает элементы, у которых значение метки `label` больше заданного значения. Применимо: логи, метрики — для числовых меток; трейсы — только для меток типа duration (временные значения). | `duration>500ms` — вернет трейсы/спаны с длительностью более 500 мс.<br/><br/>`value>0.95` — пример для метрик/логов с числовой меткой. |
| `label>=300`        | Возвращает элементы, у которых значение метки `label` больше или равно заданному значению. Применимо: логи, метрики — для числовых меток; трейсы — только для duration. | `latency>=2s` — вернет трейсы/спаны с задержкой не менее 2 с. |
| `label<300` | Возвращает элементы, у которых значение метки `label` меньше заданного значения. Применимо: логи, метрики — для числовых меток; трейсы — только для duration. | `elapsed<750ms` — вернет трейсы/спаны короче 750 мс. |
| `label<=300`        | Возвращает элементы, у которых значение метки `label` меньше или равно заданному значению. Применимо: логи, метрики — для числовых меток; трейсы — только для duration. | `duration<=1s` — вернет трейсы/спаны с длительностью до 1 с включительно. |

Для операторов `>` `>=` `<` `<=`:
- Логи и метрики: справа ожидается числовой литерал; значение метки приводится к числу. Исключение — метка `level`.
- Трейсы: сравнение поддерживается только для меток типа duration; справа ожидается литерал длительности с единицами (например, `500ms`, `2s`, `150us`). Если привести значение метки к требуемому типу не удалось, результат именно этой части выражения считается ложным.

Для поиска по меткам, хранящимся в метаинформации `meta`, указывайте полный квалификатор `meta.label_name`. Доступны те же операторы, что и для меток верхнего уровня, во всех типах телеметрии. Подробнее о метках и метаинформации — в разделе [Модель данных в Monium](data-model.md).

Поле `message` существует только у логов.

#### Специфичные ключи для трейсов {#trace-keys}

При поиске трейсов и спанов доступны дополнительные ключи:

* `span.name` — имя спана, поддерживает все строковые операторы.
* `span.id` — идентификатор спана, поддерживает операторы `=` и `!=`.
* `span.status` — статус спана: `OK`, `ERROR` или `UNKNOWN`, поддерживает операторы `=` и `!=`.
* `span.duration` — длительность спана, поддерживает операторы сравнения `>`, `>=`, `<`, `<=` с литералами длительности (например, `500ms`, `2s`).
* `span.critical_path` — принадлежность спана к критическому пути: `PRESENT` или `ABSENT`, поддерживает оператор `=`.
* `trace.id` — идентификатор трейса (для поиска логов по трейсу).

В языке запросов можно опускать любое количество ведущих нулей в значении `trace.id`. Следующие селекторы работают одинаково:

* `{trace.id="000000000000000036a91077c9806b4c"}`
* `{trace.id="000036a91077c9806b4c"}`
* `{trace.id="36a91077c9806b4c"}`

Поиск трейсов описан в разделе [Поиск трейсов и спанов](../traces/operations/traces-explorer.md).

## Использование имен запросов в качестве переменных {#query-name-as-variable}

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

Например:

A: `{project="folder__my_folder_id", cluster="default", service="custom", room="bedroom", building="home", sensor="sensor1" }`

B: `{project="folder__my_folder_id", cluster="default", service="custom", room="bedroom", building="home", sensor="sensor2" }`

C: `(A + B) / 2`

Ссылаться по имени можно только в текстовом режиме и на вышестоящие запросы в одном и том же алерте или графике. К переменным можно применять любые поддерживаемые арифметические операции и [функции](querying-functions.md) языка запросов.

## Оптимизация селекторов {#selector-performance-tuning}

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

Примеры:

* `{project = "...", service = "...", meta.order.id = "*abc*123*"}` — в запросе нет точного значения атрибутов, поэтому поиск выполняется по всему хранилищу.

* `{project, service, meta.order.id = "bf090941d4f44867"}` — точное значение позволяет выполнить поиск быстро, если `id` встречается редко.

* `{project, service, meta.order.id = "*abc*123*", meta.request.id = "c7438471-fc0f46b9bc68"}` — поиск по `order.id` с glob-шаблоном медленный, но точное значение `request.id` ускоряет запрос.

* `{project, service, geo.city = "very_small_city"}` — оптимизация работает также для меток из `labels`.

* `{project, service, geo.city = "very_small_city", meta.purchase_token = "f97b68f2450e43e4"}` — запрос быстрее предыдущего: сначала фильтрация по `geo.city`, затем по `purchase_token`.

* `{project, service, trace.id="00008dsf7d8df7d"}` — оптимизация работает для `trace.id` и `span.id`.

Высококардинальные метки, в том числе идентификаторы, рекомендуется хранить в метаинформации `meta`. Подробнее о различии между метками и метаинформацией — в разделе [Метаинформация](data-model.md#meta).

#### См. также {#see-also}

* [Модель данных в Monium](data-model.md)
* [Конфигурация объектов Monium](configuration-model.md)
* [Строка запроса в Monium](visualization/query-string.md)
* [Использование функций при поиске метрик](querying-functions.md)