# Як краще назвати свої відрізки

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

---

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

## Назви відрізків для вашої бізнес-логіки {#naming-your-business-spans}

Хоча автоматична інструментація OpenTelemetry чудово підходить для стандартних операцій (таких як вхідні HTTP-запити або виклики бази даних), найцінніші відомості часто надходять із власних відрізків, які ви додаєте до своєї бізнес-логіки. Це операції, унікальні для домену вашої програми.

Для цих власних відрізків користувачів ми рекомендуємо використовувати шаблон, запозичений з базової граматики. Прості, чіткі речення часто мають структуру «підмет ⇾ присудок ⇾ безпосередній структурний обʼєкт». «Підмет» (сервіс, що виконує роботу) вже є частиною контексту трасування. Решту цієї структури ми можемо використовувати для назви відрізку:

## {verb} {object}

Цей шаблон є описовим, легким для розуміння і допомагає підтримувати низьку [кардинальність](/docs/concepts/glossary/#cardinality)—ключове поняття, до якого ми звернемося пізніше.

- **{verb}**: Дієслово, що описує виконувану роботу (наприклад: обробити \[process\], надіслати \[send\], розрахувати \[calculate\], відобразити \[render\]).
- **{object}**: Іменник, що описує те, на що впливають (наприклад: платіж \[payment\], рахунок \[invoice\], кошик для покупок \[shopping_cart\], реклама \[ad\]).

Давайте розглянемо кілька прикладів:

| Погані назви                       | Гарні назви відрізків | Чому це краще                                                                      |
| :--------------------------------- | :-------------------- | :--------------------------------------------------------------------------------- |
| process_payment_for_user_jane_doe  | process payment       | Дієслово та обʼєкт чіткі. ID користувача належить атрибуту.                        |
| send*invoice*#98765                | send invoice          | Можна агрегувати. Легко знайти P95 затримку для надсилання всіх рахунків.          |
| render_ad_for_campaign_summer_sale | render ad             | Конкретна кампанія є деталлю, а не основною операцією. Помістіть її в атрибут.     |
| calculate_shipping_for_zip_90210   | calculate shipping    | Операція є послідовною. Поштовий індекс є параметром, а не частиною назви.         |
| validation_failed                  | validate user_input   | Зосередьтеся на операції, а не на результаті. Результат належить статусу відрізка. |

Дотримуючись формату `{verb} {object}`, ви створюєте чіткий, послідовний словник для своїх бізнес-операцій. Це робить ваші трасування надзвичайно потужними. Менеджер продукту може запитати: "Скільки часу потрібно для обробки платежів?" і інженер може відразу відфільтрувати ці відрізки та отримати відповідь.

## Чому цей шаблон працює {#why-this-pattern-works}

Отже, чому `process payment` є хорошим, а `process*invoice*#98765` поганим? Причина в **кардинальності**.

Кардинальність відноситься до кількості унікальних значень, які може мати частина даних. Назва відрізка повинна мати **низьку кардинальність**. Якщо ви включите унікальні ідентифікатори, такі як ID користувача або номер рахунку, в назву відрізка, ви створите унікальну назву для кожної окремої операції. Це заповнить вашу систему спостереження, ускладнить групування та аналіз подібних операцій і може значно збільшити витрати.

Шаблон `{verb} {object}` природно створює назви з низькою кардинальністю. Унікальні деталі з високою кардинальністю (`invoice\_#98765, user_jane_doe`) належать до **атрибутів відрізка**, які ми розглянемо в майбутньому дописі.

## З досвіду семантичних домовленостей {#learning-from-semantic-conventions}

Цей підхід `{verb} {object}` не є випадковим. Це найкраща практика, яка відображає принципи офіційних **Семантичних Домовленостей OpenTelemetry (SemConv)**. SemConv надає стандартизований набір імен для загальних операцій, що забезпечує послідовність назв відрізків для HTTP-запитів, незалежно від мови чи фреймворку.

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

Давайте розглянемо кілька прикладів з SemConv.

### Відрізки HTTP {#http-spans}

Для серверних HTTP-відрізків конвенція така: `{method} {route}`.

- **Приклад:** `GET /api/users/:ID`
- **Аналіз:** Це дієслово (`GET`), що діє на обʼєкт (`/api/users/:id`). Використання шаблону маршруту замість фактичного шляху (`/api/users/123`) є ідеальним прикладом підтримки низької кардинальності.

### Відрізки бази даних {#database-spans}

Відрізки бази даних часто дотримуються конвенції іменування `{db.operation} {db.name}.{db.sql.table}`.

- **Приклад:** `INSERT my_database.users`
- **Аналіз:** Це дієслово (`INSERT`), що діє на обʼєкт (`my_database.users`). Конкретні значення, які вставляються, мають високу кардинальність і справедливо виключаються з назви.

### Відрізки RPC {#rpc-spans}

Для віддалених викликів процедур конвенція така: `{rpc.service}/{rpc.method}`.

- **Приклад:** `com.example.UserService/GetUser`
- **Аналіз:** Хоча формат відрізняється, принцип залишається тим же. Він описує метод (`GetUser`), який є дієсловом, в межах сервісу (`com.example.UserService`), який є обʼєктом або ресурсом.

Ключовий висновок полягає в тому, що, використовуючи `{verb} {object}`, ви говорите тією ж мовою, що й інша частина вашої інструментації.

## Розвиток здорової системи {#cultivating-a-healthy-system}

Іменування відрізків не є тривіальним завданням. Це основна практика для побудови надійної та ефективної стратегії спостереження. Прийнявши чіткий, послідовний шаблон, такий як `{verb} {object}` для ваших бізнес-специфічних відрізків, ви можете перетворити свої телеметричні дані з заплутаного безладу на добре доглянуту садибу.

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

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