[Документация Yandex Cloud](../../index.md) > [Monium](../index.md) > Концепции > Модель данных

# Модель данных в Monium

В сервисе Monium действует единая модель данных для работы с телеметрией: метриками, логами и трейсами. Данные идентифицируются с помощью [объектов конфигурации](configuration-model.md) (проект, кластер, сервис) и разделяются на метки и метаинформацию.

В этом разделе описана организация данных и особенности каждого вида телеметрии. Поиск по данным — в разделе [Язык запросов в Monium](querying.md).

## Виды телеметрии и общие понятия {#telemetry-common}

* _Метрика_ — [временной ряд](https://en.wikipedia.org/wiki/Time_series), который показывает изменение какой-либо величины во времени. Например, состояние ресурса одного из сервисов Yandex Cloud: количество занятого места на диске, скорость передачи данных по сети. По метрикам можно отслеживать нагрузку на ресурсы или приложения на графиках и отправлять уведомления, когда показатели приближаются к критическим значениям.

* _Лог_ — структурированные записи событий, содержащие имя события и его атрибуты. Предназначены для поиска деталей об ошибках и расследования инцидентов.

* _Трейс_ — путь запроса через распределенную систему. Путь запроса состоит из цепочки операций (спанов) с временем начала и длительностью. Предназначен для анализа производительности приложения, локализации узких мест и поиска причин ошибок в различных сервисах, работающих совместно.

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

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

- `time` — время появления события в пользовательской системе с точностью до наносекунд.
- `project` — проект с данными определенного каталога. Идентификатор проекта — `folder__<идентификатор_каталога>`.
- `cluster` — объект Monium, как правило, окружение (инсталляция) клиентского приложения. Кластер задается в конфигурации сбора телеметрии.
- `service` — объект Monium, как правило, имя клиентского приложения (веб-сервер, база данных). Сервис задается в конфигурации сбора телеметрии.

Для идентификации и поиска данных метрикам, логам и трейсам можно назначить метки.

### Метки {#label}

_Метка_ — характеристика метрики, лога или трейса в формате `ключ: "значение"`. Обычно в качестве метки используется параметр, который принимает ограниченное множество значений. Например, код состояния HTTP, тип операций, которые выполняются в базе данных. Метки используются в языке запросов для более точного поиска данных.

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

#### Ограничения на метки и их значения {#label-limits}

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

* метрика может иметь не более 32 меток, включая обязательные `project`, `cluster`, `service`;
* строка лога может иметь не более 16 меток, включая обязательные;
* имя метки должно удовлетворять регулярному выражению `^[a-zA-Z][0-9a-zA-Z_.]{1,32}$`;
* значение метки должно удовлетворять регулярному выражению `^[ -!#-&(-)+->@-_a-{}-~]{1,200}$`, от 1 до 200 печатных ASCII-символов, кроме символов `|*?"'\`.
* поле `labels` не может содержать метки `project`, `cluster`, `service`, `name` — они зарезервированы. Их можно передавать в параметрах URL, по которому выполняется POST-запрос.

Квоты для меток в одном шарде:

* Количество меток (ключи из `labels`) в логах, записываемых в долговременное хранилище, — 1000.

Поскольку на метки есть ограничения, имена меток лучше назначать статически и не генерировать из кода (например, как `label_1`, `label_2`... `label_10`). Значения меток должны быть низкой кардинальности (например, нормально иметь в метках значения для 1000 хостов). Высококардинальные значения лучше хранить в `meta`.

Значения меток поддерживают два типа: Unicode-строки и числа (целые или вещественные). В языке запросов применяется автоматическое приведение типов в зависимости от оператора, с которым используется метка.

### Метаинформация {#meta}

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

К метаинформации предъявляются менее строгие требования, чем к меткам. Метки — это высокоселективные данные, которые помогают уменьшить область поиска, а метаинформация содержит разнородную, слабоструктурированную информацию о событии, которая позволяет получить больше деталей.

Ограничений на размер метаинформации фактически нет, он ограничен только квотами на прием данных и размером одной записи.

Ограничения для ключей в метаинформации:
* имя ключа — Unicode-последовательность печатных символов;
* длина ключа — не более 100 символов.

Ключи могут создаваться динамически и не повторяться между записями. Лимитов на количество ключей нет — ни в системе, ни в одной записи. Значения ключей не имеют фиксированного лимита, за исключением общих квот на размер записи.

{% note tip %}

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

{% endnote %}

Выбор меток или метаинформации для логов описан в разделе [Рекомендации по разметке логов](../logs/concepts/attributes-guide.md).

## Зарезервированные имена полей в метках и метаинформации {#reserved-names}

Поскольку часть атрибутов в модели данных находится на верхнем уровне, есть ряд ограничений на имена внутри меток `labels` и метаинформации `meta`.

В качестве ключей в `labels` и `meta` нельзя использовать:

Имя ключа | Описание
--- | ---
`project`, `cluster`, `service`, `name` | Атрибуты верхнего уровня
`labels.*` | Имена ключей, которые начинаются с подстроки `labels.`, в том числе и само имя ключа `labels.`
`meta.*`   | --/--
`trace.*`  | --/--
`span.*`   | --/--
`_*`       | Имена ключей, которые начинаются с символа `_`, зарезервированы для служебных целей

Также в одной записи (например, в одной строке лога) в `labels` и `meta` не должно быть одинаковых имен ключей.

## Метрики {#metric}

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

### Агрегация запросов {#aggregation}

Некоторые метрики (например, `disk.write_latency` в Yandex Compute Cloud) отслеживают большое количество запросов, которое может достигать десятков тысяч в секунду. Запросы в таких метриках изначально агрегируются в бакеты в зависимости от значения.

В таких метриках существует несколько бакетов, например `1`, `2`, `5`, `10` и т. д. Так, в бакете `1` хранятся запросы, выполнение которых заняло до 1 мс, в бакете `2` — до 2 мс, в бакете `5` — до 5 мс и т. д.

При выполнении запроса сервис измеряет время его выполнения и определяет, к какому бакету его отнести. Например, если запрос выполнился за 7 мс, то он попадет в бакет `10`, как и все другие запросы, выполнявшиеся от 5 до 10 мс.

Значение таких метрик представляет собой дробное число — среднее количество запросов за определенную единицу времени, например, за 5 секунд.

Чаще всего к таким метрикам применяется [фильтр](querying.md#histogram_percentile) `histogram_percentile`, принимающий в качестве параметра процентную долю запросов, для которой требуется рассчитать минимальное время, в которое укладывается эта доля запросов.

Например:

> Была зафиксирована одна тысяча запросов, из которых:
> - 500 запросов выполнились за 0,5 мс;
> - 499 запросов выполнились за 1,5 мс;
> - 1 запрос выполнился за 1000 мс.

Среднее арифметическое значение на один запрос составит приблизительно 2 мс. Но это значение будет мало полезно из-за высокого пикового значения, которое в нем учтено. Значительно полезнее будет знать, что максимальное время выполнения запроса составило 1000 мс, но 99% запросов уложились в 2 мс. То есть 99-й процентиль запросов составил 2 мс. Этот процентиль можно получить, передав в фильтр `histogram_percentile` значение `99`.

Также на значения в метриках влияет [политика прореживания данных](decimation.md).

### Типы метрик {#metric-types}

Тип | Описание
----- | -----
`DGAUGE` | Числовой показатель (дробное число). Показывает значение метрики в определенный момент времени. Например, количество занятой оперативной памяти.
`IGAUGE` | Числовой показатель (целое число). Показывает значение метрики в определенный момент времени.
`COUNTER` | Счетчик. Показывает значение метрики, которое растет со временем. Например, количество дней непрерывной работы сервиса.
`RATE` | Производная. Показывает изменение значения метрики во времени. Например, количество запросов в секунду.
`HIST_RATE` | Гистограммный счетчик. Показывает среднее количество событий, попавших в каждый бакет за единицу времени.

## Логи {#logs}

Единица передачи логов — _строка лога_. Строка лога представляет собой набор полей с данными.

Обязательные поля верхнего уровня (общие для всех видов телеметрии): `time`, `project`, `cluster`, `service`.

Опциональные поля верхнего уровня:

- `level` — уровень сообщения в логе: `info`, `debug`, `error`, `fatal` и другие.
- `message` — строка в формате [Unicode](https://wikipedia.org/wiki/Unicode) с произвольным текстом.
- `host` — имя хоста, с которого получена строка лога.
- `labels` — набор меток `ключ: "значение"` для объединения однотипных логов и последующего поиска и фильтрации логов.
- `meta` — набор структурированной метаинформации одной строки лога, разложенной по разным ключам.
- `trace.id` — идентификатор запроса (трейса), [Hex](https://wikipedia.org/wiki/Hexadecimal)-строка, 32 байта.
- `span.id` — идентификатор подзапроса (спана) в подмножестве одного `trace.id`, Hex-строка, 16 байт.

При передаче логов можно выбрать необходимый набор данных. Например, при неуспешном HTTP‑вызове можно записывать:

* `message` — краткое текстовое описание ошибки;
* `labels` — атрибуты для группировки и поиска: код ответа, имя метода или эндпоинта, клиент или сервис;
* `meta` — структурированные детали: [трассировка стека](https://en.wikipedia.org/wiki/Stack_trace), длительность запроса, параметры вызова.

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

### Примеры поиска и фильтрации логов {#log-examples}

* Логи, в которых метод `api/v1/push` ответил кодом, отличным от успешного:
    ```js
    {method="api/v1/push", response_code!=200}
    ```

* Логи, в которых метод `api/v1/write` вызывался клиентом `ugc`:
    ```js
    {method="api/v1/write", client_name="ugc"}
    ```

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

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

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