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

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

В этом разделе описан язык запросов для выборки и фильтрации по логам. В интерфейсе Monium и API используется единый язык запросов для получения данных. Язык позволяет применять фильтрующие выражения к каждой строчке лога. По аналогии с SQL — задавать условные выражения в часть `WHERE`.

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

Тип данных определяется из записи выражения в литеральной форме. Язык запросов поддерживает примитивные типы данных: 

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

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

    При записи чисел поддерживаются запись с мантиссой, а также следующие суффиксы:
    * `k` — 10^3^;
    * `M` — 10^6^;
    * `G` — 10^9^;
    * `T` — 10^12^;
    * `P` — 10^15^;
    * `E` – 10^18^.

    Например:

    ```
    101
    75.3
    20G
    1E-3
    ```

## Язык выборки и фильтрации логов {#selector}

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

Пример:

```js
{project="folder__b1g86q4m5vej********", service="fetcher", cluster="production", duration > 500}
```

### Операторы:

|Вид селектора | Описание | Примеры|
|-|-|-|
| `label="<value>"`   | Возвращает все логи, у которых есть метки, значения которых совпадают со значением `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`.| `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>"`| Оператор обратный `=*` ||
| `label=~"<regex>"`  | Возвращает логи, у которых значение метки `label` удовлетворяет регулярному выражению `<regex>` на языке [re2](https://github.com/google/re2/wiki/Syntax).                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `label!~"<regex>"`  | Противоположность селектору `label=~"<regex>"`.                                                                                                                                                                                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `label>300`         | Возвращает все логи, у которых значение метки `label` (возможно приведенное к типу операнда справа) больше заданного значения                                                                                                                              | `duration>500` – вернет логи, у которых метка `duration`, приведенная к числовому значению, больше 500                                                                                                                                                                                                                                                                                                                                                                      |
| `label>=300`        | Возвращает все логи, у которых значение метки `label` (возможно приведенное к типу операнда справа) больше или равно заданному значению                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `label<300`         | Возвращает все логи, у которых значение метки `label` (возможно приведенное к типу операнда справа) меньше заданного значения                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `label<=300`        | Возвращает все логи, у которых значение метки `label` (возможно приведенное к типу операнда справа) меньше или равно заданному значению                                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

Для операторов `>` `>=` `<` `<=` операнд справа всегда ожидается числовым литералом (за исключением метки `level`) и сравнение происходит с приведением типа метки так же к числу, если привести значение метки не получилось — результат вычисления именно этой части выражения считается ложным.

Для поиска по меткам, хранящимся в метаинформации `meta`, обязательно указание полного квалификатора имени `meta.label_name`, при этом доступны все те же операторы, что используются для меток с верхнего уровня и `labels`.

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

```js
....
project="folder__b1g86q4m5vej********"
service="fetcher"
cluser="production"
level=ERROR
labels={hook_type="LIVENESS", object_type="WORKLOAD", start_time=1708348144767787, fail_reason=2000, state="EHttpGetState_SUCCESS"}
meta={user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 YaBrowser/24.1.0.0 Safari/537.36"}
```
Селектор, фильтрующий строчки лога с уровнем логирования INFO или DEBUG

```js
{project="folder__b1g86q4m5vej********", service="fetcher", cluser="production", level="INFO|DEBUG"}
```

Селектор, фильтрующий строчки лога у которых в метке `fail_reason` (один из ключей в поле `labels`) содержится целое число больше 1000

```js
{project="folder__b1g86q4m5vej********", service="fetcher", cluser="production", fail_reason>1000}
```

Поиск всех ошибок, произошедших при запросе от определенного агента

```js
{project="folder__b1g86q4m5vej********", service="fetcher", cluser="production", level>="ERROR", fail_reason=200, meta.user_agent=*"Chrome"}
```

В имени метки допустимы символы `.`, они рассматриваются как часть имени одной метки. Такие символы в селекторе не экранируются.

```js
{exception.type="java.lang.RuntimeException"}
```

или для `meta`

```js
{meta.exception.message="cannot replace metrics*"}
```

## Минимально необходимый селектор {#required-selector}

Для селектора, есть минимально необходимый набор меток, которые обязательны в каждом запросе. Фактически это означает максимальную область поиска для одного селектора. Это обязательное наличие меток `project` + `service` или `log_group_id`.

Ограничения на минимальный селектор

| Метка     | Ограничение                                                                                                                          | Пример                                                                                           |
|-----------|--------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| `project` | должен иметь единое значение и точное соответствие, не является обязательной меткой, если в селекторе имеется метка `trace.id`    | `{project=folder__b1g86q4m5vej********, service=coremon}` `{trace.id="fcdcbceff9cb39ef"}`                             |
| `service` | может иметь множественное значение и точное соответствие, не является обязательной меткой, если в селекторе имеется метка `trace.id` | `{project=folder__b1g86q4m5vej********, service="coremon\|fetcher"}` `{project=folder__b1g86q4m5vej********, trace.id="fcdcbceff9cb39ef"}` |

## Ограничение на метки {#labels-limitation}

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

| Метка               | Ограничение                                                                                                                                                                                | Пример                                                                               |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| `project`           | должен иметь единое значение и точное соответствие                                                                                                                                      | `{project=folder__b1g86q4m5vej********, service=coremon}`                                                 |
| `cluster`/`service` | могут иметь множественное значение и точное соответствие                                                                                                                                   | `{project=folder__b1g86q4m5vej********, service=coremon}` `{project=folder__b1g86q4m5vej********, service="coremon\|fetcher"}` |
| `host`/`message`    | не применяются операторы `<` `<=` `>` `>=`                                                                                                                                                 |                                                                                      |
| `trace.id`          | может иметь множественное значение и точное соответствие                                                                                                                                   | `{project=folder__b1g86q4m5vej********, trace.id="36a91077c9806b4c\|cc26b62976badd0"}`                    |
| `span.id`           | может иметь множественное значение и точное соответствие                                                                                                                                   | `{project=folder__b1g86q4m5vej********, trace.id="cc26b62976badd0", span.id="0cc26b62976badd0"}`          |
| `level`             | значения должны быть из скоупа `TRACE`&#124;`DEBUG`&#124;`INFO`&#124;`WARN`&#124;`ERROR`&#124;`FATAL`, для `level` доступны сравнения `<` `<=` `>` `>=` в порядке, заданном в перечислении | `{level >= WARN}`                                                                    |

## Особенности работы с trace.id

В языке запросов допускается опускать произвольное количество leading zeroes в значении `trace.id`.
Так, следующие селекторы эквивалентны:

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

## Рекомендации по написанию эффективных селекторов {#selector-performance-tuning}

Для разреженных данных ([подробнее](https://at.yandex-team.ru/clubs/monitoring/4960)) используются оптимизации, позволяющие искать только в части хранилища, поэтому **чем более точно запрос сужает выборку, тем быстрее он работает**. Например:

* `{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`, но можем по `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`

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