# Як називати атрибути відрізків

LLMS index: [llms.txt](/llms.txt)

---

Ласкаво просимо до другої частини нашої серії про найкращі практики іменування в OpenTelemetry. У [попередньому дописі](/blog/2025/how-to-name-your-spans/), ми розглянули як називати відрізки, використовуючи шаблон `{verb} {object}`. Сьогодні ми заглибимось в атрибути відрізків — багаті контекстуальні дані, які перетворюють ваші трейси з простих журналів операцій на потужні інструменти для налагодження та аналізу.

Цей посібник призначений для розробників, які:

- **Інструментують власні застосунки** власними відрізками та атрибутами
- **Збагачують телеметрію** поза межами автоматичної інструментації
- **Створюють бібліотеки**, які інші будуть інструментувати

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

## Почніть із семантичних домовленостей {#start-with-semantic-conventions}

Ось найважливіше правило, яке заощадить ваш час та покращить сумісність: **якщо існує [семантична домовленість](/docs/specs/semconv/registry/attributes/) OpenTelemetry і семантика відповідає вашому випадку використання, використовуйте її**.

Це не просто питання зручності — це про створення телеметрії, яка безперешкодно інтегрується з ширшою екосистемою OpenTelemetry. Коли ви використовуєте стандартизовані назви атрибутів, ваші дані автоматично працюють з наявними дашбордами, правилами сповіщень та інструментами аналізу.

### Коли семантика збігається, використовуйте домовленість {#when-semantics-match-use-the-convention}

| Ваша потреба              | Використовуйте цю семантичну домовленість | Чому                                            |
| :------------------------ | :---------------------------------------- | :---------------------------------------------- |
| Метод HTTP-запиту         | `http.request.method`                     | Стандартизовано для всієї HTTP-інструментації   |
| Назва колекції бази даних | `db.collection.name`                      | Працює з інструментами моніторингу баз даних    |
| Ідентифікація сервісу     | `service.name`                            | Основний атрибут ресурсу для кореляції сервісів |
| Адреса мережевого вузла   | `network.peer.address`                    | Стандарт для налагодження на рівні мережі       |
| Класифікація помилок      | `error.type`                              | Забезпечує послідовний аналіз помилок           |

Ключовий принцип — **семантична відповідність важливіша за вподобання в іменуванні**. Навіть якщо ви надаєте перевагу `database_table` замість `db.collection.name`, використовуйте семантичну домовленість, коли вона точно описує ваші дані.

### Коли семантика не збігається, не намагайтеся її підігнати {#when-semantics-dont-match-dont-force-it}

Уникайте спокуси неправильно використовувати семантичні домовленості:

| Не робіть так                                     | Чому це неправильно                           |
| :------------------------------------------------ | :-------------------------------------------- |
| Використання `db.collection.name` для імені файлу | Файли та колекції баз даних — різні концепції |
| Використання `http.request.method` для бізнес-дій | "approve_payment" не є HTTP-методом           |
| Використання `user.id` для ID транзакції          | Користувачі та транзакції — різні сутності    |

Неправильне використання семантичних домовленостей гірше, ніж створення власних атрибутів — це створює плутанину та порушує роботу інструментів, які очікують стандартну семантику.

## Золоте правило: Спочатку домен, а не компанія {#golden-rule-domain-first-never-company-first}

Коли вам потрібні власні атрибути поза межами семантичних домовленостей, найважливіший принцип: **починайте з домену або технології, ніколи з назви вашої компанії чи застосунку**.

Цей принцип здається очевидним, але його постійно порушують в індустрії. Ось чому це важливо і як зробити це правильно.

### Чому іменування "компанія-спочатку" не працює {#why-company-first-naming-fails}

| Погана назва атрибута       | Проблеми                                                 |
| :-------------------------- | :------------------------------------------------------- |
| `og.user.id`                | Префікс компанії засмічує глобальний простір імен        |
| `myapp.request.size`        | Специфічний для застосунку, не використовується повторно |
| `acme.inventory.count`      | Ускладнює кореляцію зі стандартними атрибутами           |
| `shopify_store.product.sku` | Непотрібно привʼязує концепцію до одного постачальника   |

Такі підходи створюють атрибути, які:

- Складно корелювати між командами та організаціями
- Неможливо повторно використовувати в різних контекстах
- Привʼязані до постачальника та негнучкі
- Несумісні з цілями інтероперабельності OpenTelemetry

### Успішні приклади "домен-спочатку" {#domain-first-success-stories}

| Хороша назва атрибута | Чому це працює                                      |
| :-------------------- | :-------------------------------------------------- |
| `user.id`             | Універсальна концепція, незалежна від постачальника |
| `request.size`        | Повторно використовуваний у різних застосунках      |
| `inventory.count`     | Чітка, специфічна для домену концепція              |
| `product.sku`         | Стандартна термінологія e-commerce                  |
| `workflow.step.name`  | Загальна концепція управління процесами             |

Цей підхід створює атрибути, які є універсально зрозумілими, можуть бути повторно використані іншими, хто стикається з подібними проблемами, та орієнтовані на майбутнє.

## Розуміння структури: Крапки та підкреслення {#understanding-structure-dots-and-underscores}

Назви атрибутів OpenTelemetry слідують специфічному структурному шаблону, який урівноважує читабельність із послідовністю. Розуміння цього шаблону допомагає створювати атрибути, які природно поєднуються зі стандартними семантичними домовленостями.

### Використовуйте крапки для ієрархічного розділення {#use-dots-for-hierarchical-separation}

Крапки (`.`) розділяють ієрархічні компоненти, які слідують шаблону:
`{домен}.{компонент}.{властивість}`

Приклади з семантичних домовленостей:

- `http.request.method` — Домен HTTP, компонент запиту, властивість метод
- `db.collection.name` — Домен бази даних, компонент колекції, властивість імʼя
- `service.instance.id` — Домен сервісу, компонент екземпляру, властивість ID

### Використовуйте підкреслення для багатослівних компонентів {#use-underscores-for-multiword-components}

Коли один компонент містить кілька слів, використовуйте підкреслення (`_`):

- `http.response.status_code` — "status_code" є одним логічним компонентом
- `system.memory.usage_percent` — "usage_percent" є одним концептом вимірювання

### Створюйте глибші ієрархії за потреби {#create-deeper-hierarchies-when-needed}

Ви можете робити глибші вкладення, коли це додає ясності:

- `http.request.body.size`
- `k8s.pod.label.{key}`
- `messaging.kafka.message.key`

Кожен рівень повинен представляти значущу концептуальну межу.

## Зарезервовані простори імен: Що ніколи не можна використовувати {#reserved-namespaces-what-you-must-never-use}

Певні простори імен строго зарезервовані, і порушення цих правил може порушити ваші дані телеметрії.

### Простір імен `otel.*` заборонений {#the-otel-namespace-is-off-limits}

Префікс `otel.*` виключно зарезервований для специфікації OpenTelemetry. Він використовується для вираження концепцій OpenTelemetry у форматах телеметрії, які нативно їх не підтримують.

Зарезервовані атрибути `otel.*` включають:

- `otel.scope.name` — Назва області інструментації
- `otel.status_code` — Код статусу відрізка
- `otel.span.sampling_result` — Рішення про семплінг

**Ніколи не створюйте атрибути, що починаються з `otel.`** Будь-які доповнення до цього простору імен повинні бути затверджені як частина специфікації OpenTelemetry.

### Інші зарезервовані атрибути {#other-reserved-attributes}

Специфікація також резервує ці конкретні назви атрибутів:

- `error.type`
- `exception.message`, `exception.stacktrace`, `exception.type`
- `server.address`, `server.port`
- `service.name`
- `telemetry.sdk.language`, `telemetry.sdk.name`, `telemetry.sdk.version`
- `url.scheme`

## Шаблони семантичних домовленостей {#semantic-convention-patterns}

Найкращий спосіб розвинути хорошу інтуїцію щодо іменування атрибутів — це вивчення семантичних домовленостей OpenTelemetry. Вони представляють тисячі годин роботи експертів з observability.

### Шаблони організації доменів {#domain-organization-patterns}

Зверніть увагу, як семантичні домовленості організовуються навколо чітких доменів:

#### Інфраструктурні домени {#infrastructure-domains}

- `service.*` — Ідентичність сервісу та метадані
- `host.*` — Інформація про хост/машину
- `container.*` — Інформація про контейнерне середовище
- `process.*` — Процеси операційної системи

#### Комунікаційні домени {#communication-domains}

- `http.*` — Специфіка HTTP протоколу
- `network.*` — Інформація мережевого рівня
- `rpc.*` — Атрибути віддаленого виклику процедур
- `messaging.*` — Системи черг повідомлень

#### Домени даних {#data-domains}

- `db.*` — Операції з базами даних
- `url.*` — Компоненти URL

### Універсальні шаблони властивостей {#universal-property-patterns}

У всіх доменах зʼявляються послідовні шаблони для загальних властивостей:

#### Властивості ідентифікації {#identification-properties}

- `.name` — Читабельні ідентифікатори (`service.name`, `container.name`)
- `.id` — Системні ідентифікатори (`container.id`, `process.pid`)
- `.version` — Інформація про версію (`service.version`)
- `.type` — Класифікація (`messaging.operation.type`, `error.type`)

#### Мережеві властивості {#network-properties}

- `.address` — Мережеві адреси (`server.address`, `client.address`)
- `.port` — Номери портів (`server.port`, `client.port`)

#### Властивості вимірювання {#measurement-properties}

- `.size` — Вимірювання в байтах (`http.request.body.size`)
- `.count` — Кількості (`messaging.batch.message_count`)
- `.duration` — Вимірювання часу (`http.server.request.duration`)

При створенні власних доменів, дотримуйтесь цих же шаблонів. Для управління інвентарем, розгляньте:

- `inventory.item.name`
- `inventory.item.id`
- `inventory.location.address`
- `inventory.batch.count`

## Безпечне створення власних доменів {#creating-custom-domains-safely}

Іноді ваша бізнес-логіка вимагає атрибутів поза наявними семантичними домовленостями. Це нормально — OpenTelemetry не може охопити кожен можливий бізнес-домен.

### Рекомендації для безпечного створення власних доменів {#guidelines-for-safe-custom-domains}

1. **Обирайте описові, загальні назви**, які інші могли б повторно використати.
2. **Уникайте специфічної для компанії термінології** в назві домену.
3. **Дотримуйтесь ієрархічних шаблонів**, встановлених семантичними домовленостями.
4. **Розгляньте, чи міг би ваш домен стати майбутньою семантичною домовленістю**.

### Приклади добре спроектованих користувацьких атрибутів {#examples-of-well-designed-custom-attributes}

| Домен     | Хороші атрибути                          | Чому вони працюють                               |
| :-------- | :--------------------------------------- | :----------------------------------------------- |
| Бізнес    | `payment.method`, `order.status`         | Чіткі, повторно використовувані бізнес-концепції |
| Логістика | `inventory.location`, `shipment.carrier` | Специфічні для домену, але переносні             |
| Процес    | `workflow.step.name`, `approval.status`  | Загальне управління процесами                    |
| Контент   | `document.format`, `media.codec`         | Універсальні концепції контенту                  |

## Рідкісний виняток: Коли префікси мають сенс {#the-rare-exception-when-prefixes-make-sense}

У рідкісних випадках вам можуть знадобитися префікси компанії або застосунку. Це зазвичай відбувається, коли ваш власний атрибут може конфліктувати з атрибутами з інших джерел у розподіленій системі.

**Розгляньте префікси, коли:**

- Ваш атрибут може конфліктувати з атрибутами постачальників у розподіленій системі.
- Ви інструментуєте пропрієтарну технологію, яка дійсно специфічна для компанії.
- Ви фіксуєте внутрішні деталі реалізації, які не повинні бути узагальнені.

Для більшості атрибутів бізнес-логіки, дотримуйтесь іменування "домен-спочатку".

## Ваш план дій {#your-action-plan}

Правильне іменування атрибутів відрізків створює дані телеметрії, які підтримуються, сумісні та цінні для всієї вашої організації. Ось ваш план дій:

1. **Завжди спочатку перевіряйте семантичні домовленості** — Використовуйте їх, коли семантика збігається.
2. **Починайте з домену, ніколи з компанії** — Створюйте незалежні від постачальника атрибути.
3. **Поважайте зарезервовані простори імен** — Особливо уникайте `otel.*`.
4. **Дотримуйтесь ієрархічних шаблонів** — Послідовно використовуйте крапки та підкреслення.
5. **Будьте готові до повторного використання** — Думайте за межами поточних потреб.

Дотримуючись цих принципів, ви не просто вирішуєте сьогоднішні проблеми інструментації — ви робите внесок у більш узгоджену, сумісну екосистему спостереження, яка приносить користь усім.

У наступному дописі цієї серії ми перейдемо від відрізків до метрик — досліджуючи, як називати кількісні вимірювання, які розповідають нам про те, як працюють наші системи, і чому ті самі принципи розділення та "домен-спочатку" застосовуються до найважливіших чисел.