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

# Преобразование входных данных

На данный момент Monium поддерживает прием данных только в формате [OpenTelemetry](https://opentelemetry.io/). Формат API и данных описан в [proto-спецификации](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/logs/v1/logs_service.proto#L33C14-L33C38).

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

## Преобразования атрибутов {#transformations}

Атрибуты из ресурсов (`ResourceLogs.resource.attributes`), instrumentation scope (`ScopeLogs.scope.attributes`) и строчек лога (`LogRecord.attributes`) объединяются и переносятся в метки (`labels`) и метаинформацию (`meta`) по следующему алгоритму:

1. На каждом уровне (**resource**/**scope**/**log**) собираются атрибуты и распределяются на `labels` и `meta`:
   * Атрибуты, имена которых начинаются с `labels.`, попадут в `labels` (префикс `labels.` будет удален).
   * Атрибуты, имена которых начинаются с `meta.`, будут записаны в `meta` (префикс `meta.` будет удален).
   * Все остальные атрибуты попадут в `meta`, за исключением [известных атрибутов](#well-known-attributes).
   * Атрибуты, ключи которых начинаются с символа подчеркивания `_` или содержат непечатные символы, будут отброшены. Количество отброшенных атрибутов будет отражено в [метрике](#invalid-attributes-destiny).
2. `labels` и `meta` со всех уровней (**resource**/**scope**/**log**) объединяются, наибольший приоритет имеют атрибуты уровня **log**, меньший приоритет у атрибутов уровня **scope**, самый низкий — у атрибутов уровня **resource**. Подробнее в [таблице приоритетов](#priorities).
3. Значения в атрибутах с типом `int64` или `double` остаются числами. Остальные типы приводятся к строкам:
   * Bool — строка со значением `true` или `false`.
   * Байты сериализуются как base64-строка ([RFC 4648](https://datatracker.ietf.org/doc/html/rfc4648#section-4)).
   * Массивы и словари сериализуются аналогично формату JSON.
4. Атрибуты из `labels`, не удовлетворяющие [ограничениям на лейблы](../../concepts/data-model.md#labels), переносятся на уровень `meta` (существующий атрибут удаляется).
5. Атрибуты из `meta`, не удовлетворяющие ограничениям на метаинформацию, отбрасываются. Количество отброшенных атрибутов будет отражено в [метрике](#invalid-attributes-destiny).


### Приоритеты {#priorities}

#### Приоритеты для атрибутов в `labels`
| Атрибут                               | Resource | Scope | Log |
|---------------------------------------|----------|-------|-----|
| валидное значение лейбла `labels.abc` | 2        | 1     | 0   |

(0 — наибольший приоритет, 2 — самый низкий приоритет)

#### Приоритеты для атрибутов в `meta`
| Атрибут                                 | Resource | Scope | Log |
|-----------------------------------------|----------|-------|-----|
| `abc`                                   | 8        | 6     | 4   |
| `meta.abc`                              | 7        | 5     | 3   |
| невалидное значение лейбла `labels.abc` | 2        | 1     | 0   |

(0 — наибольший приоритет, 8 — самый низкий приоритет)

### Известные атрибуты {#well-known-attributes}

Некоторые системные атрибуты считаются метками без префикса `labels.`:
- `project`
- `cluster`
- `service`, `service.name`
- `host`, `host.name`, `hostname`
- `service.component`
- `service.version`
- `deployment.environment`
- `dc`

{% note warning %}

Атрибут `request_id` также считается известной меткой, но в будущем будет мигрировать на `meta`.

{% endnote %}

{% note warning %}

Системные атрибуты `project`, `cluster`, `service`, `host` ожидаются на уровне ресурса.

{% endnote %}

Особенности преобразования зарезервированных меток:

Если значение найдено по первому (самому приоритетному) ключу из списка и оно не пустое и не null, оно записывается в соответствующую метку атрибута. Использованный ключ удаляется. Сохранение остальных ключей из списка не гарантируется.

| Метка в otel формате (ключ атрибута)   | Преобразуется в (лейбл атрибута) |
|----------------------------------------|----------------------------------|
| `service`/`service.name`               | `service`                        |
| `host`/`host.name`/`hostname`          | `host`                           |
| `labels.component`/`service.component` | `component`                      |
| `labels.version`/`service.version`     | `version`                        |
| `labels.env`/`deployment.environment`  | `env`                            |
| `labels.dc`/`dc`                       | `dc`                             |


## Невалидные атрибуты {#invalid-attributes-destiny}

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

## Поддерживаемые поля OTLP {#supported-fields-otlp}

### Уровень Scope {#scope-level}

[Поля уровня Scope](https://github.com/open-telemetry/opentelemetry-proto/blob/e4fd4f681f583b1bdea4d375ad19ddc0dc1f2e9c/opentelemetry/proto/common/v1/common.proto#L71) превращаются в метки:
* Поле `name` в атрибут `scope.name`;
* Поле `version` в атрибут `scope.version`.

Полученные атрибуты имеют наименьший приоритет.

### Уровень Log {#log-level}

#### Идентификаторы трейса и спана {#trace-span-ids}

Поля `trace_id` и `span_id` являются опциональными. Значения полей должны иметь длину:
* `trace_id` — 16-байтовый идентификатор;
* `span_id` — 8-байтовый идентификатор.

Валидные идентификаторы будут сохранены в систему в HEX-формате в `trace.id` и `span.id` соответственно.

Подробное описание приведено в [спецификации](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/logs/v1/logs.proto#L187-L212).

В формате JSON представление `trace_id` и `span_id` зависит от протокола:

| Протокол  | Представление |
|-----------|---------------|
| HTTP+JSON | HEX-строка    |
| GRPC+JSON | Base64-строка |