IKuznetsov: Новая страница: «= API метрик — выражения метрик = Метрические выражения позволяют использовать простые арифметические операции прямо в селекторе метрики. Например, это выражение вычисляет отношение (в процентах) двух показателей: `metric1 / metric2 * 100` В качестве опер...»

2026-07-29T03:03:44Z

Новая страница: «= API метрик — выражения метрик = Метрические выражения позволяют использовать простые арифметические операции прямо в селекторе метрики. Например, это выражение вычисляет отношение (в процентах) двух показателей: <code>metric1 / metric2 * 100</code> В качестве опер...»

Новая страница

= API метрик — выражения метрик =

Метрические выражения позволяют использовать простые арифметические операции прямо в селекторе метрики.

Например, это выражение вычисляет отношение (в процентах) двух показателей:

<code>metric1 / metric2 * 100</code>

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

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

= Ограничения =

* Селектор должен содержать как минимум один ключ метрики.
* В одном запросе можно запросить данные по 10 показателям. Для целей этого ограничения одно выражение (например, <code>metric2 + metric2</code>) считается одной метрикой.

= Приоритет =

Применяются стандартные математические правила очередности операций:

# Скобки, метрические преобразования
# Отрицание
# Умножение, деление
# Сложение, вычитание
# Агрегация

Если в цепочке преобразований было применено агрегирование, используется именно это агрегирование. Если преобразование не применялось, используется агрегирование по умолчанию. Ваши операнды метрик могут иметь разные агрегирования. Например, <code>metric:max - metric:min</code>.

= Разрешение выражений =

Метрические выражения обрабатываются следующим образом:

# Сформируйте пары кортежей для каждой пары метрик.
# Выровняйте точки данных в каждом кортеже.
# Примените арифметические операции к выровненным точкам данных.

== Кортежи ==

Арифметические операции используют данные кортежей (уникальных комбинаций метрики — измерения — значения измерения) метрик. Идентичные кортежи каждой метрики объединяются в пары, а затем их данные выравниваются.

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

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

== Точки данных ==

После формирования пар кортежей точки данных выравниваются, а затем к выровненным точкам данных применяется необходимая арифметическая операция.

* Если хотя бы одна из выровненных точек данных равна null, выражение преобразуется в null.
* Если в операции используется число, оно выравнивается с каждой точкой данных операнда метрики.
* Если один показатель представляет собой отдельную точку данных, а другой — ряд данных, то эта отдельная точка данных соответствует каждой точке данных ряда.
* Если оба показателя представляют собой одну точку данных, то точки данных совпадают, и результирующий временной интервал охватывает обе точки данных.
* Если оба показателя являются последовательными рядами, то точки данных выравниваются по временным меткам.
* Для любых невыровненных точек данных выражение преобразуется в null.

= Передовые методы =

== Использовать только при необходимости ==

Используйте выражение метрики только в том случае, если без него вы не сможете достичь своей цели. Допустим, вы хотите рассчитать среднее использование ЦП двумя хостами, <code>HOST-001</code> и <code>HOST-002</code>. Вы можете сделать это с помощью выражения метрики:

<pre>
(
builtin:host.cpu.usage:filter(eq("dt.entity.host","HOST-001")):splitBy()
+
builtin:host.cpu.usage:filter(eq("dt.entity.host","HOST-002")):splitBy()
)
/2
</pre>

У этого подхода есть две проблемы. Во-первых, выражение трудночитаемо и, следовательно, подвержено синтаксическим ошибкам. Во-вторых, если один из хостов находится в автономном режиме, результат выражения будет пустым. Хотя вторую проблему можно было бы решить с помощью преобразования по умолчанию, использование агрегирования по среднему значению более эффективно:

<pre>
builtin:host.cpu.usage
:filter(
or(
eq("dt.entity.host","HOST-001"),
eq("dt.entity.host","HOST-002")
)
)
:splitBy()
:avg
</pre>

== Не переводите единицы измерения ==

Не используйте метрические выражения для преобразования единиц измерения данных. Вместо этого используйте преобразование <code>toUnit</code>. Единственное исключение из этого правила — единицы измерения, которые не поддерживаются Ключ-АСТРОМ. Используйте запрос '''GET all units''', чтобы получить список поддерживаемых единиц измерения.

== Ограничить использование преобразований ==

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

Рассмотрим следующий запрос, который пытается сложить 10 периодов наибольшего использования ЦП с 10 периодами простоя ЦП.

<pre>
builtin:host.cpu.usage:sort(value(avg,descending)):limit(10)
+
builtin:host.cpu.idle:sort(value(avg,descending)):limit(10)
</pre>

Если у вас большая среда с сотнями хостов, маловероятно, что 10 хостов с самым высоким уровнем загрузки ЦП окажутся среди 10 хостов с самым длительным временем простоя ЦП. Операнды не будут иметь совпадающих кортежей, поэтому результат выражения будет пустым. Решение состоит в том, чтобы применить ограничение к результату выражения:

<pre>
(
builtin:host.cpu.usage
+
builtin:host.cpu.idle
)
:sort(value(auto,descending))
:limit(10)
</pre>

== Устраните пробелы в данных с помощью преобразования по умолчанию ==

Преобразование по умолчанию особенно полезно для выражений метрик. Хотя обычно преобразование не заполняет точки данных, <code>null</code> если метрика не имеет ни одной точки данных в заданном временном интервале, в контексте выражения метрики его семантика несколько иная. Пока метрика с любой стороны выражения имеет хотя бы одну точку данных, преобразование заполнит пробелы. Однако, если все метрики в выражении содержат отсутствующие данные, преобразование вернет пустые результаты.

Рассмотрим пример выражения для расчета коэффициента ошибок для ключевых действий пользователя:

<pre>
builtin:apps.other.keyUserActions.reportedErrorCount.os
/
builtin:apps.other.keyUserActions.requestCount.os
</pre>

Если за указанный вами период времени было много запросов, но ни одной ошибки, результат будет пустым, хотя коэффициент ошибок <code>0</code> был бы более информативным. Этого можно добиться с помощью преобразования <code>default(0)</code>:

<pre>
builtin:apps.other.keyUserActions.reportedErrorCount.os:default(0)
/
builtin:apps.other.keyUserActions.requestCount.os
</pre>

API метрик — выражения метрик - История изменений