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

Ласкаво просимо до другої частини нашої серії про найкращі практики іменування в OpenTelemetry. У попередньому дописі, ми розглянули як називати відрізки, використовуючи шаблон {verb} {object}. Сьогодні ми заглибимось в атрибути відрізків — багаті контекстуальні дані, які перетворюють ваші трейси з простих журналів операцій на потужні інструменти для налагодження та аналізу.

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

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

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

Почніть із семантичних домовленостей

Ось найважливіше правило, яке заощадить ваш час та покращить сумісність: якщо існує семантична домовленість OpenTelemetry і семантика відповідає вашому випадку використання, використовуйте її.

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

Коли семантика збігається, використовуйте домовленість

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

Коли семантика не збігається, не намагайтеся її підігнати

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

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

Золоте правило: Спочатку домен, а не компанія

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

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

Чому іменування “компанія-спочатку” не працює

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

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

Успішні приклади “домен-спочатку”

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

Розуміння структури: Крапки та підкреслення

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

Використовуйте крапки для ієрархічного розділення

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

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

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

Використовуйте підкреслення для багатослівних компонентів

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

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

Створюйте глибші ієрархії за потреби

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

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

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

Зарезервовані простори імен: Що ніколи не можна використовувати

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

Простір імен otel.* заборонений

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

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

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

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

Інші зарезервовані атрибути

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

• 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

Шаблони семантичних домовленостей

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

Шаблони організації доменів

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

Інфраструктурні домени

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

Комунікаційні домени

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

Домени даних

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

Універсальні шаблони властивостей

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

Властивості ідентифікації

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

Мережеві властивості

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

Властивості вимірювання

• .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

Безпечне створення власних доменів

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

Рекомендації для безпечного створення власних доменів

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

Приклади добре спроектованих користувацьких атрибутів

Рідкісний виняток: Коли префікси мають сенс

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

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

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

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

Ваш план дій

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

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

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

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

• ←Попередня
• Наступна→