Як краще назвати свої відрізки
Одним з найважливіших, але часто недооцінених аспектів хорошої інструментації є призначення імен. Ця публікація є першою в серії, присвяченій мистецтву та науці призначення імен в OpenTelemetry. Ми почнемо з відрізків, які є будівельними блоками розподіленого трасування, і відразу на початку надамо вам найважливішу інформацію: як призначати імена відрізкам, що описують вашу унікальну бізнес-логіку.
Назви відрізків для вашої бізнес-логіки
Хоча автоматична інструментація OpenTelemetry чудово підходить для стандартних операцій (таких як вхідні HTTP-запити або виклики бази даних), найцінніші відомості часто надходять із власних відрізків, які ви додаєте до своєї бізнес-логіки. Це операції, унікальні для домену вашої програми.
Для цих власних відрізків користувачів ми рекомендуємо використовувати шаблон, запозичений з базової граматики. Прості, чіткі речення часто мають структуру «підмет ⇾ присудок ⇾ безпосередній структурний обʼєкт». «Підмет» (сервіс, що виконує роботу) вже є частиною контексту трасування. Решту цієї структури ми можемо використовувати для назви відрізку:
{verb} {object}
Цей шаблон є описовим, легким для розуміння і допомагає підтримувати низьку кардинальність—ключове поняття, до якого ми звернемося пізніше.
- {verb}: Дієслово, що описує виконувану роботу (наприклад: обробити [process], надіслати [send], розрахувати [calculate], відобразити [render]).
- {object}: Іменник, що описує те, на що впливають (наприклад: платіж [payment], рахунок [invoice], кошик для покупок [shopping_cart], реклама [ad]).
Давайте розглянемо кілька прикладів:
| Погані назви | Гарні назви відрізків | Чому це краще |
|---|---|---|
| process_payment_for_user_jane_doe | process payment | Дієслово та обʼєкт чіткі. ID користувача належить атрибуту. |
| sendinvoice#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}, ви створюєте чіткий, послідовний словник для своїх бізнес-операцій. Це робить ваші трасування надзвичайно потужними. Менеджер продукту може запитати: “Скільки часу потрібно для обробки платежів?” і інженер може відразу відфільтрувати ці відрізки та отримати відповідь.
Чому цей шаблон працює
Отже, чому process payment є хорошим, а process*invoice*#98765 поганим? Причина в кардинальності.
Кардинальність відноситься до кількості унікальних значень, які може мати частина даних. Назва відрізка повинна мати низьку кардинальність. Якщо ви включите унікальні ідентифікатори, такі як ID користувача або номер рахунку, в назву відрізка, ви створите унікальну назву для кожної окремої операції. Це заповнить вашу систему спостереження, ускладнить групування та аналіз подібних операцій і може значно збільшити витрати.
Шаблон {verb} {object} природно створює назви з низькою кардинальністю. Унікальні деталі з високою кардинальністю (invoice\_#98765, user_jane_doe) належать до атрибутів відрізка, які ми розглянемо в майбутньому дописі.
З досвіду семантичних домовленостей
Цей підхід {verb} {object} не є випадковим. Це найкраща практика, яка відображає принципи офіційних Семантичних Домовленостей OpenTelemetry (SemConv). SemConv надає стандартизований набір імен для загальних операцій, що забезпечує послідовність назв відрізків для HTTP-запитів, незалежно від мови чи фреймворку.
Коли ви уважно подивитеся, ви побачите, що цей самий шаблон опису операції з ресурсом відображається в усіх конвенціях. Дотримуючись його для своїх власних відрізків, ви узгоджуєтеся з встановленою філософією всієї екосистеми OpenTelemetry.
Давайте розглянемо кілька прикладів з SemConv.
Відрізки HTTP
Для серверних HTTP-відрізків конвенція така: {method} {route}.
- Приклад:
GET /api/users/:ID - Аналіз: Це дієслово (
GET), що діє на обʼєкт (/api/users/:id). Використання шаблону маршруту замість фактичного шляху (/api/users/123) є ідеальним прикладом підтримки низької кардинальності.
Відрізки бази даних
Відрізки бази даних часто дотримуються конвенції іменування {db.operation} {db.name}.{db.sql.table}.
- Приклад:
INSERT my_database.users - Аналіз: Це дієслово (
INSERT), що діє на обʼєкт (my_database.users). Конкретні значення, які вставляються, мають високу кардинальність і справедливо виключаються з назви.
Відрізки RPC
Для віддалених викликів процедур конвенція така: {rpc.service}/{rpc.method}.
- Приклад:
com.example.UserService/GetUser - Аналіз: Хоча формат відрізняється, принцип залишається тим же. Він описує метод (
GetUser), який є дієсловом, в межах сервісу (com.example.UserService), який є обʼєктом або ресурсом.
Ключовий висновок полягає в тому, що, використовуючи {verb} {object}, ви говорите тією ж мовою, що й інша частина вашої інструментації.
Розвиток здорової системи
Іменування відрізків не є тривіальним завданням. Це основна практика для побудови надійної та ефективної стратегії спостереження. Прийнявши чіткий, послідовний шаблон, такий як {verb} {object} для ваших бізнес-специфічних відрізків, ви можете перетворити свої телеметричні дані з заплутаного безладу на добре доглянуту садибу.
Добре названий відрізок — це подарунок вашому майбутньому «я» та вашій команді. Він забезпечує ясність під час стресових відмов, дозволяє проводити потужний аналіз продуктивності та, в кінцевому підсумку, допомагає вам створювати краще, надійніше програмне забезпечення.
У нашому наступному пості в цій серії ми заглибимося в наступний рівень деталей: атрибути відрізків. Ми дослідимо, як додати багатий, висококардинальний контекст до ваших відрізків, який необхідний для глибокого налагодження, не компрометуючи агрегованість ваших назв відрізків.