Трейси

Шлях запиту через ваш застосунок.

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

Розгляньмо це на прикладі трьох одиниць роботи, представлених як Відрізки:

Примітка

Наступні приклади JSON не представляють конкретний формат, і особливо не OTLP/JSON, який є більш детальним.

hello span:


{
  "name": "hello",
  "context": {
    "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "051581bf3cb55c13"
  },
  "parent_id": null,
  "start_time": "2022-04-29T18:52:58.114201Z",
  "end_time": "2022-04-29T18:52:58.114687Z",
  "attributes": {
    "http.route": "some_route1"
  },
  "events": [
    {
      "name": "Guten Tag!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

Це кореневий відрізок, що позначає початок і кінець всієї операції. Зверніть увагу, що він має поле trace_id, яке вказує на відрізок, але не має parent_id. Це означає, що це кореневий відрізок.

hello-greetings span:


{
  "name": "hello-greetings",
  "context": {
    "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "5fb397be34d26b51"
  },
  "parent_id": "051581bf3cb55c13",
  "start_time": "2022-04-29T18:52:58.114304Z",
  "end_time": "2022-04-29T22:52:58.114561Z",
  "attributes": {
    "http.route": "some_route2"
  },
  "events": [
    {
      "name": "hey there!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    },
    {
      "name": "bye now!",
      "timestamp": "2022-04-29T18:52:58.114585Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

Цей відрізок охоплює конкретні завдання, такі як привітання, і його батьком є відрізок hello. Зверніть увагу, що він має той самий trace_id, що й кореневий відрізок, що вказує на те, що він є частиною того ж самого відрізка. Крім того, він має parent_id, який збігається з span_id відрізка hello.

hello-salutations span:


{
  "name": "hello-salutations",
  "context": {
    "trace_id": "5b8aa5a2d2c872e8321cf37308d69df2",
    "span_id": "93564f51e1abe1c2"
  },
  "parent_id": "051581bf3cb55c13",
  "start_time": "2022-04-29T18:52:58.114492Z",
  "end_time": "2022-04-29T18:52:58.114631Z",
  "attributes": {
    "http.route": "some_route3"
  },
  "events": [
    {
      "name": "hey there!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

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

Ці три блоки JSON мають однаковий trace_id, а поле parent_id представляє ієрархію. Це робить їх Трейсом!

Ще одна річ, яку ви помітите, це те, що кожен Відрізок виглядає як структурований лог. Це тому, що він таким і є! Один зі способів думати про Трейси є те, що вони є колекцією структурованих логів з контекстом, кореляцією, ієрархією та іншими вбудованими елементами. Однак ці “структуровані логи” можуть надходити з різних процесів, сервісів, віртуальних машин, центрів обробки даних тощо. Це дозволяє трасуванню представляти кінцевий вигляд будь-якої системи.

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

Постачальник трейсерів

Постачальник Трейсерів (іноді називається TracerProvider) є фабрикою для Tracer-ів. У більшості застосунків постачальник трейсерів ініціалізується один раз, і його життєвий цикл відповідає життєвому циклу застосунку. Ініціалізація постачальника трейсерів також включає ініціалізацію ресурсів та експортерів. Це зазвичай перший крок у трасуванні з OpenTelemetry. У деяких SDK мов програмування глобальний постачальник трейсерів вже ініціалізований для вас.

Трейсер

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

Експортери трейсів

Експортери Трейсів надсилають трейси споживачу. Цей споживач може бути стандартним виводом для налагодження та розробки, OpenTelemetry Collector або будь-яким відкритим або бекендом постачальника на ваш вибір.

Поширення контексту

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

Відрізки

Відрізок представляє одиницю роботи або операцію. Відрізки є будівельними блоками Трейсів. У OpenTelemetry вони включають наступну інформацію:

Назва
Ідентифікатор батьківського відрізка (порожній для кореневих відрізків)
Час початку та закінчення
Контекст відрізка
Атрибути
Події відрізка
Посилання відрізка
Статус відрізка

Приклад відрізка:


{
  "name": "/v1/sys/health",
  "context": {
    "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
    "span_id": "086e83747d0e381e"
  },
  "parent_id": "",
  "start_time": "2021-10-22 16:04:01.209458162 +0000 UTC",
  "end_time": "2021-10-22 16:04:01.209514132 +0000 UTC",
  "status_code": "STATUS_CODE_OK",
  "status_message": "",
  "attributes": {
    "net.transport": "IP.TCP",
    "net.peer.ip": "172.17.0.1",
    "net.peer.port": "51820",
    "net.host.ip": "10.177.2.152",
    "net.host.port": "26040",
    "http.method": "GET",
    "http.target": "/v1/sys/health",
    "http.server_name": "mortar-gateway",
    "http.route": "/v1/sys/health",
    "http.user_agent": "Consul Health Check",
    "http.scheme": "http",
    "http.host": "10.177.2.152:26040",
    "http.flavor": "1.1"
  },
  "events": [
    {
      "name": "",
      "message": "OK",
      "timestamp": "2021-10-22 16:04:01.209512872 +0000 UTC"
    }
  ]
}

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

Контекст відрізка

Контекст відрізка є незмінним обʼєктом на кожному відрізку, який містить наступне:

Ідентифікатор Трейсу, що представляє трейс, до якого належить відрізок
Ідентифікатор Відрізка
Прапори Трейсу, двійкове кодування, що містить інформацію про трейс
Стан Трейсу, список пар ключ-значення, які можуть містити інформацію про трейс, специфічну для постачальника

Контекст відрізка є частиною відрізка, яка серіалізується та поширюється разом з Розподіленим Контекстом та Багажем.

Оскільки Контекст Відрізка містить Ідентифікатор Трейсу, він використовується при створенні Посилань Відрізка.

Атрибути

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

Наприклад, якщо відрізок відстежує операцію додавання товару до кошика користувача в системі електронної комерції, ви можете зафіксувати ідентифікатор користувача, ідентифікатор товару для додавання до кошика та ідентифікатор кошика.

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

Атрибути мають наступні правила, які реалізуються кожним SDK мов програмування:

Ключі повинні бути ненульовими рядковими значеннями
Значення повинні бути ненульовими рядковими, булевими, числом з рухомою комою, цілими числами або масивами цих значень

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

Події відрізка

Подія Відрізка може бути розглянута як структуроване повідомлення журналу (або анотація) на Відрізку, яке зазвичай використовується для позначення значущої, одиничної точки в часі під час тривалості Відрізка.

Наприклад, розглянемо два сценарії у вебоглядачі:

Відстеження завантаження сторінки
Позначення моменту, коли сторінка стає інтерактивною

Відрізок найкраще підходить для першого сценарію, оскільки це операція з початком і кінцем.

Подія Відрізка найкраще підходить для відстеження другого сценарію, оскільки вона представляє значущу, одиничну точку в часі.

Коли використовувати події відрізка замість атрибутів відрізка

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

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

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

Посилання відрізка

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

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

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

Ви можете звʼязати останній відрізок з першого трейсу з першим відрізком у другому трейс. Тепер вони повʼязані один з одним.

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

Для отримання додаткової інформації див Span Links.

Статус відрізка

Кожен відрізок має статус. Можливі три значення:

Unset
Error
Ok

Стандартне значення — Unset. Статус відрізка, який є Unset, означає, що операція, яку він відстежував, успішно завершилася без помилки.

Коли статус відрізка Error, це означає, що під час операції, яку він відстежує, сталася помилка. Наприклад, це може бути через помилку HTTP 500 на сервері, який обробляє запит.

Коли статус відрізка Ok, це означає, що відрізок був явно позначений розробником застосунку як безпомилковий. Хоча це не інтуїтивно, не обов’язково встановлювати статус відрізка як Ok, коли відомо, що відрізок завершився без помилки, оскільки це покривається Unset. Що робить Ok, так це представляє однозначний “остаточний виклик” щодо статусу відрізка, який був явно встановлений користувачем. Це корисно в будь-якій ситуації, коли розробник бажає, щоб не було іншої інтерпретації відрізка, окрім “успішного”.

Щоб повторити: Unset представляє відрізок, який завершився без помилки. Ok — це, коли розробник явно позначає відрізок як успішний. У більшості випадків не потрібно явно позначати відрізок як Ok.

Тип відрізків

Коли відрізок створюється, він є одним з Client, Server, Internal, Producer або Consumer. Цей тип відрізка надає підказку бекенду трасування про те, як слід зібрати трейс. Відповідно до специфікації OpenTelemetry, батьком серверного відрізка часто є віддалений клієнтський відрізок, а дочірнім відрізком клієнтського відрізка зазвичай є серверний відрізок. Аналогічно, батьком відрізка споживача (consumer) завжди є виробник (producer), а дочірнім відрізком виробника завжди є споживач. Якщо не вказано, тип відрізка вважається внутрішнім.

Для отримання додаткової інформації про SpanKind дивіться SpanKind.

Client

Клієнтський відрізок представляє синхронний вихідний віддалений виклик, такий як вихідний HTTP-запит або виклик бази даних. Зверніть увагу, що в цьому контексті “синхронний” не стосується async/await, а того, що він не ставиться в чергу для подальшої обробки.

Server

Серверний відрізок представляє синхронний вхідний віддалений виклик, такий як вхідний HTTP-запит або віддалений виклик процедури.

Internal

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

Producer

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

Consumer

Відрізки споживача представляють обробку завдання, створеного виробником, і можуть початися довго після того, як відрізок виробника вже закінчився.

Специфікація

Для отримання додаткової інформації дивіться специфікацію трейсів.

Відгук

Чи це було корисним?

Дякуємо. Ми цінуємо ваші відгуки!

Будь ласка, дайте нам знати як ми можемо покращити цю сторінку. Ми цінуємо ваші відгуки!

Востаннє змінено June 5, 2025: [uk] spellchecking (8ca5a3a5)