# Асоціація контексту трейсу в OBI

> Дізнайтеся, як OBI асоціює вихідні запити з вхідними батьківськими запитами для розподілених трейсів.

---

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

---

## Вступ {#introduction}

Розподілене трасування в OBI складається з двох частин:

1. Знайти активний батьківський запит для вихідної роботи.
2. Поширити обране значення W3C `traceparent` у вихідному запиті.

Посібник [Розподілені трейси](../distributed-traces/) описує, як OBI записує контекст трейсу у вихідний HTTP/gRPC трафік. Ця сторінка описує першу частину: як OBI асоціює вихідний запит із вхідним запитом, який його спричинив, і де ця асоціація може зазнати невдачі.

OBI виконує цю асоціацію на основі спостережень eBPF та середовища виконання. Він не читає довільні змінні застосунку або обʼєкти контексту фреймворку. Натомість він використовує підтримувані механізми передачі контексту, активність сокетів та звʼязки потоків ОС, описані нижче.

## Як OBI знаходить батьківський запит {#how-obi-finds-the-parent-request}

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

Крок асоціації є окремим від кроку, який записує вихідне значення `traceparent`. Наприклад, мовно-нейтральне поширення контексту на рівні мережі може асоціювати HTTP/1.x запити між мовами, але не записує контекст для gRPC або HTTP/2 трафіку. Поширення контексту Go на рівні бібліотеки може записувати контекст для HTTP/2 та gRPC лише на нових, не-HTTPS зʼєднаннях; повторно використані зʼєднання HTTP/2/gRPC ще не підтримуються. Інші обмеження описані в [розподілених трейсах](../distributed-traces/#go-context-propagation-by-instrumenting-at-library-level).

## Специфічна для середовища виконання асоціація {#runtime-specific-association}

OBI має підтримку, специфічну для середовища виконання, для поширених асинхронних моделей та моделей з потоками:

| Середовище або компонент | Механізм асоціації                                                                                                                                               | Підтримувана область та обмеження                                                                                                                                                                      |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Go                       | Відстежує контекст трейсу між goroutine.                                                                                                                         | Go `1.18+`. Підтримує до 6 рівнів вкладеності goroutine.                                                                                                                                               |
| Node.js                  | Використовує асинхронні хуки Node.js для оновлення контексту активного запиту перед асинхронними зворотними викликами та асоціації вихідних сокетів із вхідними. | Node.js `8.0+`. Власна обробка `SIGUSR1` може заважати підтримці Node.js у OBI.                                                                                                                        |
| Java                     | Відстежує передачі через поширені JDK API завдань, включаючи `Executor`, `Runnable`, `Callable` та `ForkJoinTask`.                                               | JDK `8+`. Підтримує пошук батьківського завдання до 3 рівнів передач. Власні черги або реалізації планувальників, які не використовують ці JDK API, можуть повернутися до мовно-нейтральної поведінки. |
| Java virtual threads     | Відстежує операції монтування та демонтування віртуальних потоків, щоб контекст запиту привʼязувався до віртуального потоку, а не лише до потоку ОС-носія.       | JDK `21+`. Збагачення логів пропускається для запитів, що обробляються на віртуальних потоках.                                                                                                         |
| Python asyncio           | Відстежує поточне завдання `asyncio`, створення дочірніх завдань, успадкований контекст та роботу `asyncio.to_thread()`.                                         | Підтримується для Python `3.9+` з циклом подій `uvloop`.                                                                                                                                               |
| Ruby Puma                | Асоціює запити, коли потік-реактор Puma передає прийняту роботу робочому потоку.                                                                                 | Потребує Puma `5.0+`. Сервіси Ruby, які не обслуговуються Puma, використовують мовно-нейтральну поведінку.                                                                                             |
| NGINX                    | Асоціює вхідний запит із upstream зʼєднанням, вибраним NGINX.                                                                                                    | Застосовується до upstream проксіювання NGINX, яке спостерігається OBI.                                                                                                                                |

Ці механізми розроблені для типової поведінки фреймворків. Наприклад, OBI
зазвичай може асоціювати батьківські та дочірні spans для:

- Go обробників, які створюють короткі дерева goroutine під час обробки запиту.
- Node.js HTTP фреймворків, які використовують стандартне асинхронне середовище Node.js.
- Java сервлетних застосунків, таких як багато сервісів Spring MVC, коли вихідна робота залишається на потоці запиту або диспетчеризується через поширені JDK API завдань, перелічені вище.
- Python `asyncio` сервісів, що працюють на `uvloop`, включаючи роботу, створену за допомогою `asyncio.create_task()`, `asyncio.gather()` та `asyncio.to_thread()`.
- Ruby застосунків, які обслуговуються Puma.
- NGINX зворотнього проксі до upstream сервісів.

## Мовно-нейтральна асоціація {#language-agnostic-association}

Коли специфічна для середовища виконання асоціація недоступна, OBI використовує мовно-нейтральні сигнали, видимі через eBPF:

- Той самий потік ОС обробляє вхідний запит та вихідний запит.
- Вихідний запит виконується з дочірнього потоку або процесу, який OBI може повʼязати з оригінальним потоком запиту.
- Потік запиту виконує налаштування сокета або перевірки зʼєднання перед тим, як вихідний запит завершується іншим робочим потоком.

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

## Обмеження {#limitations}

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

- Робота поміщається в чергу фреймворку, і вся активність вихідних сокетів відбувається пізніше на робочому потоці, який OBI не може повʼязати з оригінальним запитом.
- Реактивний фреймворк або фреймворк з циклом подій передає роботу через структури планування, які не охоплені зазначеними вище механізмами. Spring WebFlux, Netty/Reactor та власні Java планувальники все ще можуть втрачати асоціацію, якщо передача також не проходить через спостережуваний JDK API завдань або мовно-нейтральний сигнал сокета.
- Фонове завдання, повторна спроба або відкладене завдання продовжується після того, як контекст оригінального запиту більше не активний.
- Кілька логічних запитів мультиплексуються на одному потоці ОС, і немає підтримуваного специфічного для середовища виконання механізму для ідентифікації активного логічного завдання.
- Метод активного поширення контексту не може записати контекст трейсу для вихідного протоколу. Зокрема, мовно-нейтральне поширення на рівні мережі не підтримує gRPC або HTTP/2.

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