IKuznetsov: Новая страница: «На этой странице описан протокол ввода метрических данных в Ключ-АСТРОМ. == Синтаксис == О...»

2025-12-26T00:12:25Z

Новая страница: «На этой странице описан протокол ввода метрических данных в Ключ-АСТРОМ. == Синтаксис == О...»

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

На этой странице описан протокол ввода метрических данных в Ключ-АСТРОМ.

== Синтаксис ==
Общий синтаксис ввода метрических данных выглядит следующим образом:
{| class="wikitable"
|metric.key,dimensions payload
|}

=== Ключ метрики <code>Необходимо</code> ===
Ключ к отправляемой вами метрике. Он состоит из разделов, разделенных точками, например: <code>first.second.third</code>.

Допустимые символы: строчные и прописные буквы, цифры, дефисы (<code>-</code>) и подчеркивания (<code>_</code>). Действуют следующие ограничения:

* Использование нелатинских букв (например, <code>ö</code>) не допускается.
* Ключи метрик не могут начинаться с цифры или дефиса (<code>-</code>).
* Разделы не могут начинаться с дефиса (<code>-</code>).
* Длина ключа должна находиться в диапазоне от 3 до 255 символов.

Метрический ключ заканчивается либо на первой запятой (если вы указываете размеры), либо на первом пробеле (если вы опускаете размеры).

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

=== Измерения <code>Необязательно</code> ===
Если вы хотите опустить измерения, укажите полезную нагрузку сразу после ключа метрики, разделив ее пробелом.

Размеры указываются парами <code>key="value"</code>. Можно указать до 50 размеров, разделяемых запятыми (<code>,</code>).

Допустимые символы для ключа: строчные буквы, цифры, дефисы (<code>-</code>), точки (<code>.</code>), двоеточия (<code>:</code>) и подчеркивания (<code>_</code>). Специальные буквы (например, <code>ö</code>) не допускаются. Ключ может иметь следующий формат <code>key.key-section</code>:

Передайте значение измерения в виде строки в кавычках. Если вы хотите передать кавычки (<code>"</code>) и/или обратные косые черты (<code>\</code>) в значении измерения, убедитесь, что вы экранируете их обратной косой чертой (<code>\</code>). Например:
{| class="wikitable"
|workHours,team="devops\\bugfixing",project="\"product\"_improvement" 1000
|}
В настоящее время мы поддерживаем только одно значение измерения для каждого ключа измерения. Если один и тот же ключ измерения указан несколько раз в одном полезном потоке данных (например, <code>ipaddress="192.168.100.1",ipaddress="10.0.0.1"</code>), полезный поток данных считается допустимым, но принимается только одно значение.

==== Зарезервированные размеры Ключ-АСТРОМ ====
Ключом <code>dt.entity.<entity_type></code> является зарезервированный ключ измерения Ключ-АСТРОМ, который связывает метрику с отслеживаемым объектом, указанным в качестве значения измерения (например, измерение <code>dt.entity.host=HOST-06F288EE2A930951</code> сопоставляет точки данных с хостом с идентификатором '''HOST-06F288EE2A930951''').

=== Полезная нагрузка <code>Необходимо</code> ===
Общий формат полезной нагрузки следующий:
{| class="wikitable"
|format,dataPoint timestamp
|}

==== Формат <code>Необязательно</code> ====
Вы можете указать полезную нагрузку в двух форматах: '''gauge''' (<code>gauge</code>) или '''count value''' (<code>count</code>). Укажите формат перед указанием точек данных и отделите его от точек данных запятой (например, <code>gauge,80.6</code>).

В классических метриках ключ метрики может ссылаться только на один тип полезной нагрузки. Таким образом, предоставленный вами ключ метрики автоматически дополняется суффиксом <code>.count</code> для типа полезной нагрузки, <code>count</code> если ключ уже не заканчивается на <code>.count</code>. И наоборот, если ключ метрики типа '''gauge''' заканчивается на <code>.count</code>, он дополняется суффиксом <code>.gauge</code>.

Метрики '''Grail''' не учитывают суффиксы <code>.count</code> и <code>.gauge</code>.
{| class="wikitable"
!gauge
!count
|-
|Для формата индикатора можно указать следующие сводные статистические данные:

* <code>min</code>
* <code>max</code>
* <code>sum</code>
* <code>count</code>— количество измерений, включенных в точку данных.

Формат можно опустить, если вы используете полезную нагрузку в виде одного значения индикатора. В этом случае предоставленное значение будет использоваться для всех сводок, а счетчик будет установлен на <code>1</code>.

Например, полезная нагрузка <code>80.6</code> равна <code>gauge,min=80.6,max=80.6,sum=80.6,count=1</code>.
|Использование формата подсчета автоматически создаст новую метрику с ключом <code>your-metric-key.count</code>. Чтобы указать значение подсчета, необходимо указать поле delta: <code>count,delta=500</code>.

Точки данных этого <code>count</code> типа представляют собой разницу между предыдущей и текущей точками данных. Например, если начальная точка данных имеет значение <code>500</code>, а вторая точка данных имеет значение <code>1,000</code>, то фактическое сохраненное значение на момент времени второй точки данных будет равно <code>1,500</code>
|}

==== Точка данных <code>Необходимо</code> ====
В качестве точки данных может использоваться одна или, в случае формата индикатора, несколько мер. Для нескольких мер необходимо предоставить сводные статистические данные. Необходимо указать все сводные данные.

Данные типа <code>count</code> представляют собой разницу между предыдущей и текущей точками данных.

==== Отметка времени <code>Необязательно</code> ====
Формат метки времени — миллисекунды UTC. Допустимый диапазон — от 1 часа в прошлом до 10 минут в будущем. Данные с метками времени, выходящими за пределы этого диапазона, отклоняются.

Если метка времени не указана, используется '''текущая метка времени сервера'''.

=== Метаданные <code>Необязательно</code> ===
Вы можете предоставлять пользовательские метаданные метрик через протокол приема. Протокол приема поддерживает только создание метаданных. Если метаданные для одной и той же метрики указаны несколько раз в полезной нагрузке, используется только первое вхождение. Для просмотра или обновления метаданных используйте либо браузер метрик, либо API настроек.
{| class="wikitable"
|#metric.key <payload-format> dt.meta.<property>="<value>"
|}
Вместо <code>count<payload-format>metric-key.count</code>. Используйте формат подсчета, и он автоматически создаст новую метрику с ключом <code>gauge</code>.

Доступны следующие свойства. Чтобы указать несколько свойств, разделите их запятой (<code>,</code>).
{| class="wikitable"
!Ключ
!Тип
!Описание
|-
|dt.meta.displayName
|String
|Название метрики в пользовательском интерфейсе.
|-
|dt.meta.description
|String
|Краткое описание метрики.
|-
|dt.meta.unit
|String
|Единица измерения метрики.
|}

== Примеры ==
Общий синтаксис ввода метрических данных выглядит следующим образом:
{| class="wikitable"
|metric.key,dimensions payload

<nowiki>#</nowiki>metric.key <payload-format> dt.meta.<property1>="<value>", dt.meta.<property2>="<value>"
|}

=== Размеры ===
Вот пример метрики, использующей несколько измерений <code>team</code> и <code>businessapp</code> описывающей представленные данные.
{| class="wikitable"
|mymetric,team=teamA,businessapp=hr 1000
|}
Вот тот же пример с отметкой времени для каждой точки данных.
{| class="wikitable"
|mymetric,team=teamA,businessapp=hr 1000 1609459200000
|}

=== Gauge метрики ===
По умолчанию используется тип данных '''Gauge''', поэтому вы можете оставить его необязательным, если хотите отправлять значения '''Gauge''':
{| class="wikitable"
|cpu.temperature,hostname=hostA,cpu=1 55

cpu.temperature,hostname=hostA,cpu=2 45
|}
Вот пример <code>gauge</code>, но с использованием соответствующего типа данных.
{| class="wikitable"
|cpu.temperature,hostname=hostA,cpu=1 gauge,45
|}
Вы также можете предоставить сводную информацию о нескольких точках данных, записанных на стороне клиента, перед отправкой в Ключ-АСТРОМ. В приведенном ниже примере суммируются 2 точки данных, и в одной строке отправляются минимальное, максимальное, суммарное значение и количество точек данных.
{| class="wikitable"
|cpu.temperature,hostname=hostA,cpu=1 gauge,min=17.1,max=17.3,sum=34.4,count=2
|}
Также можно связать измерения с существующими объектами-хостами, используя <code>dt.entity.host</code> зарезервированный ключ измерения.
{| class="wikitable"
|cpu.temperature,dt.entity.host=HOST-4587AE40F95AD90D,cpu=1 gauge,min=17.1,max=17.3,sum=34.4,count=2
|}

=== COUNT метрики ===
Для метрики типа COUNT дельта рассчитывается и предоставляется клиентом, отправляющим метрику в Ключ-АСТРОМ, что в приведенном ниже примере представляет собой количество новых пользователей, зарегистрированных по регионам.
{| class="wikitable"
|new_user_count,region=EAST count,delta=50

new_user_count,region=WEST count,delta=150
|}

=== Создание метаданных ===
Вот пример предоставления метаданных для метрики <code>cpu.temperature</code>.
{| class="wikitable"
|#cpu.temperature gauge dt.meta.unit=count,dt.meta.description="The temperature of the CPU",dt.meta.displayname="CPU temperature"
|}

Протокол приема метрических данных - История изменений

IKuznetsov: Новая страница: «На этой странице описан протокол ввода метрических данных в Ключ-АСТРОМ. == Синтаксис == О...»