Ми зламали OTel Demo
Якщо ви вже деякий час користуєтеся Демо, то могли помітити кілька структурних змін останнім часом і, можливо, навіть розлютилися через те, що щось перестало працювати як очікувалося. Ми поділяємо ваші розчарування і цілком їх розуміємо. На жаль, не було кращого способу змінити речі, не зламавши наявний процес роботи.
Дещо з того, що ви знали, зникло. Було додано нові сервіси. Імена атрибутів змінилися. Якщо у вас були дашборди з власними метриками — тепер усе зламано.
Це не було випадковістю.
OTel Demo завжди була живою референсною імплементацією, місцем, де спільнота показує, що можна зробити за допомогою OTel. Згодом ми накопичили елементи, які заважали нам рухатися в потрібному напрямку. У версії 3.0 ми їх прибираємо. Ми робимо це свідомо, навіть якщо це спричиняє певні короткострокові незручності, і цілком навмисно.
Ось основні моменти того, що змінилося.
Що ми зламали (і чому)
Якщо ви оновлюєте версію, одразу ж помітите дві зміни: одна з них порушить роботу ваших інформаційних панелей, а інша — спосіб запуску демо-версії локально або у вашому форку.
Перейменування, якого ніхто не хотів, але яке було потрібне всім
Ця зміна заслуговує на окремий розділ, оскільки вона стосується всіх сервісів і призведе до порушення роботи ваших наявних панелей моніторингу та запитів: усі власні атрибути телеметрії були перейменовані з app.* на demo.*.
Абсолютно всі. app.product.id тепер називається demo.product.id. app.order.id — це demo.order.id. app.payment.amount — це demo.payment.amount. І так далі, у всіх сервісах. Але чому?
Коли ми запускали OTel Demo у 2022 році, app.* не був зарезервованим атрибутом, і ми побудували всі наші власні атрибути та метрики в цьому просторі імен. Минув час, і у 2023 році app.* було додано до проєкту для опису атрибутів, повʼязаних із клієнтськими застосунками (наприклад, вебзастосунки або мобільні застосунки).
Але якщо це було запроваджено у 2023 році, чому Демо все ще використовувало його?
Що ж, ми можемо назвати дві основні причини:
- Нам були потрібні інструменти, які б допомогли з цим.
- Нам було потрібно більше людей, які б допомогли з цим завданням.
Перше вирішив Martin Thwaites, коли приніс OpenTelemetry Weaver у Демо. Друге вирішилося за допомогою Florian Bourgey, який став учасником Демо через менторську програму Bloomberg. Це лише показує, як тісно OTel Demo повʼязана з усією екосистемою OTel.
Від docker-compose.yaml до compose.yaml, і режим для кожного випадку використання
Ще одна кардинальна зміна: docker-compose.yaml зник. Тепер це compose.yaml, розбитий на кілька файлів, і тепер підтримує кілька різних способів запуску Демо — від повного стандартного стеку до легших комбінацій, які вимикають Kafka, стек спостережуваності або обидва.
Навіщо так ускладнювати собі життя? Є дві причини: зручність обслуговування та полегшення життя власникам форків. OTel Demo — це проєкт з найбільшою кількістю форків у організації OTel: 6 859 форків, і завдяки цій гнучкості налаштування розробники цих форків можуть не зберігати повні копії наших файлів compose та конфігурації Collector, а натомість накладати свої зміни поверх них. Це також означає, що постачальники, які розгортають власний бекенд, можуть запускати Demo без перешкод з боку нашого стеку спостережуваності, замість того, щоб видаляти його вручну.
Що ми додали
Оскільки питання, повʼязані зі змінами, що впливають на сумісність, вже вирішено, ось що справді нового зʼявилося у версії 3.0.
Головна новинка: Agentic Demo
Чи намагалися ви колись простежити агентну AI-систему і дивувалися, як це взагалі має виглядати? Який відрізок представляє «агент вирішив, який інструмент використати»? Як виміряти затримку LLM, коли є кешування? Як виглядає повний трейс від початку до кінця? Які аргументи використав агент для виклику інструмента? Яке загальне використання токенів для повного робочого процесу?
Версія 3.0 нарешті дає нам реальну відповідь на ці запитання.
Знадобилося чимало часу, щоб це дійсно додати.
Ми додали три абсолютно нові сервіси, які утворюють повний, спостережуваний AI-стек:
- Агент LangGraph ReAct, який приймає запити користувачів, розмірковує про них і обирає правильні інструменти для виклику та повернення відповіді користувачеві. Він також підтримує багатокрокові запити, де користувачі можуть ставити уточнювальні запитання щодо згенерованих відповідей.
- Сервер MCP (Model Context Protocol), який надає можливості Демо у вигляді інструментів, які агент може виявляти та викликати.
- Інтерфейс чатбота, де реальні користувачі можуть взаємодіяти з агентом у реальному часі.
Агент підтримує як рідні інструменти LangGraph, так і інструменти MCP, включає кешування відповідей LLM і (що найважливіше для нас) повністю інструментований за допомогою OpenTelemetry. Кожен виклик інструмента, кожна взаємодія з LLM, кожен крок міркування забезпечує можливість розподіленого трасування від чатбота до агента, потім від агента до MCP, від MCP до інших мікросервісів через фронтенд і назад до користувача. Усі дані телеметрії проходять через конвеєр OTel Collector.
Говорячи про конвеєр OTel, оскільки ми є OpenTelemetry Demo, ми дотримуємося семантичних домовленостей OTel, тому ми також додали процесор gen-ai normalizer до Collector, щоб конвертувати телеметрію Traceloop/OpenLLMetry в офіційні семантичні домовленості gen_ai.*.
Якщо ви будуєте AI-системи і розмірковуєте, як правильно спостерігати за ними за допомогою OpenTelemetry, тепер ви можете запустити Демо і побачити, як це виглядає на практиці.
Безперервне профілювання
Безперервне профілювання — це те, що ми хотіли мати в Демо вже давно. Ми почали це обговорення ще у 2024 році. Версія 3.0 нарешті його постачає. Ми додали підтримку безперервного профілювання з використанням firepit як бекенду з вебінтерфейсом для перегляду профілів. Тепер Демо охоплює повну картину: трейси, метрики, логи та профілі — усе проходить через один конвеєр.
OpAMP сервер
Усе в Демо надсилає сигнали одному екземпляру Collector, але реальні розгортання не використовують один Collector. Вони використовують десятки, іноді тисячі, розподілені між сервісами, регіонами та командами. І коли ви досягаєте такого масштабу, постає нове питання: як дізнатися, яку конфігурацію запускає кожен із цих Collector’ів, і як її змінити, не заходячи через SSH на кожну машину?
Саме цю проблему вирішує протокол OpAMP (Open Agent Management Protocol), і версія 3.0 додає OpAMP сервер до Демо, щоб ви могли бачити його в роботі від початку до кінця.
Механіка: Collector уже має вбудоване OpAMP-розширення. Коли воно налаштоване, це розширення відкриває WebSocket-зʼєднання з OpAMP сервером і починає постійно звітувати про стан Collectorʼа (версію, ОС, поточну конфігурацію та статус справності).
У Демо ви можете спостерігати це за адресою http://localhost:8080/opamp/. Інтерфейс показує Collector, який звітує, і ви можете переглянути всі деталі Collectorʼа, а також повну активну конфігурацію.
Це основа для майбутніх оновлень, де буде дозволена віддалена конфігурація.
Що ми покращили
Версія 3.0 — це не лише нові та зламані речі. Вона також робить наявні частини Демо кращими.
Відтворення реальних промислових середовищ
У реальних промислових системах співіснують різні стандарти інструментування. Ви не починаєте з чистого аркуша. Щоб відобразити цю реальність, сервіс Ad тепер експонує точку доступу Prometheus /metrics з власним лічильником demo_ad_served_total{category}, який збирає OTel Collector через ресивер prometheus/ad. Це наближає Демо до того, з чим ви дійсно стикаєтеся у виробничих умовах: система, де не кожен сервіс говорить однією мовою інструментування, і OTel Collector — це те, що все повʼязує докупи.
Ми також додали підтримку SQLCommenter для сервісу Product Catalog. Запити до бази даних тепер несуть контекст трейсу OpenTelemetry, вбудований у SQL-коментарі, що дозволяє корелювати розподілені трейси з логами запитів PostgreSQL — ще один патерн прямо з реальної практики спостережуваності.
Новий генератор навантаження
Locust справлявся зі своїм завданням ще з моменту першого релізу, але мав велике дерево залежностей Python (понад тисячу рядків зафіксованих вимог). У версії 3.0 його замінено на k6 — інструмент для навантажувального тестування, який поставляється у вигляді єдиного бінарного файлу на Go, а скрипт навантажувального тестування було перероблено з нуля на його основі.
Центральний елемент — нове власне розширення xk6-otel, яке вбудовує OpenTelemetry Go SDK безпосередньо в JavaScript-рантайм k6. Кожен сценарій відкриває реальний OTel-відрізок для кожного завдання, вставляє W3C traceparent у кожен вихідний запит і поширює той самий baggage, що й старі хуки Locust, тому трафік генератора навантаження виглядає так само, як і раніше.
Є дві основні переваги. Вбудовані тестові метрики k6 (віртуальні користувачі (VU), тривалість запитів тощо) надсилаються через OTLP, що означає, що тепер і «як пройшов тест», і «що згенерував тест» потрапляють в один конвеєр. А найбільше вражає споживання памʼяті. Новий генератор навантаження тепер працює з лімітом памʼяті 512 МіБ, тоді як Locust використовував 1 500 МіБ.
Новий тестовий набір
Ми побудували фреймворк перевірки телеметрії, який дійсно валідує наскрізний конвеєр спостережуваності. Фреймворк проходиться по трейсах у Jaeger, щоб перевірити звʼязки між сервісами (переконуючись, що кожен відрізок коректно проходить через систему), метрики в Prometheus і логи в OpenSearch.
Це не та робота, яка робить анонси релізу захопливими, але ми можемо впевнено сказати, що тепер додаємо PR із набагато більшою впевненістю, коли це існує.
Негламурна робота: розчищення беклогу з 62 вразливостей
Не все в цьому релізі — новий сервіс чи нова можливість. Деяка частина — це просто борги, які тихо накопичувалися, і в цьому циклі ми нарешті сплатили велику їх частину.
Раніше цього року Piotr Kiełkowicz звʼязався з нами, перевіривши результати оцінки OpenSSF Scorecard для Demo: було виявлено 62 вразливості, більшість із яких повʼязані зі купою застарілих, не обʼєднаних PR-ів від Dependabot, що постійно збільшувалася. Цей застій існував через банальну, але добре знайому причину: обмеженість ресурсів супровідників. Оскільки кількість затверджувачів була недостатньою, оновлення залежностей накопичувалися швидше, ніж їх встигали перевірити та впевнено об’єднати, а саме впевненість і була справжнім «вузьким місцем», адже ніхто не хоче обʼєднувати велику кількість оновлень залежностей у проєкті такого розміру, не маючи можливості дізнатися, чи щось непомітно не зламалося.
Piotr почав потроху розгрібати беклог, і час збігся з іншою частиною цього релізу: новим фреймворком перевірки телеметрії, який ми вже згадували. Щойно ми отримали автоматизовані перевірки, які проходять по трейсах, метриках і логах від початку до кінця, злиття оновлення залежностей перестало бути стрибком віри. Саме ця впевненість дозволила беклогу дійсно рухатися, а не просто зростати.
Результат: з 62 позначених проблем до однозначного числа, причому понад 300 CVE було вирішено загалом у міру того, як розчищення набирало обертів у всьому графі залежностей. Проєкт помітно здоровіший завдяки цьому.
Що відкриває версія 3.0
Якщо відступити й подивитися на форму цього релізу, OpenTelemetry Demo більше не просто «застосунок для трейсування кошика покупця». Це всеосяжна, референсна імплементація, яка тепер охоплює:
- Агентні AI-системи та способи їх інструментування
- Безперервне профілювання разом із трейсами, метриками та логами
- Змішане налаштування інструментування для демонстрації zero-code інструментування, а також ручного інструментування
- Оцінку прапорців OpenFeature із телеметрією
- Кореляцію запитів до бази даних через SQLCommenter
- Різні стандарти для відтворення реальних операційних сценаріїв
І багато іншого, що не вмістилося б в один допис.
Заклик до дії
Через перейменування атрибутів і перехід на compose.yaml ваш форк або інструкції вашого постачальника десь зламані. На завершення, звертаємося до кожного постачальника, який має інструкції з налаштування OTel Demo для надсилання даних у свій бекенд (так, усі 45, перелічені в головному README). Будь ласка, перегляньте ваші поточні інструкції та оновіть їх, бо вони більше не працюють. Ми створили issue для відстеження всіх оновлень і видалимо неперевірені записи з головного README через 60 днів після релізу 3.0.
Подяка
Усе це не відбулося б без людей, які зробили свій внесок. Велика подяка кожному, хто відкрив PR, переглянув його, повідомив про проблему або приєднався до дзвінка SIG під час цього циклу. PR із розчищенням, перейменування телеметрії, нові сервіси — усе це було роботою спільноти, і це видно.
Особлива подяка:
- Felix George, за терпіння та відданість, завдяки яким агентні сервіси були злиті.
- Dónal O’Sullivan та Florian Lehner, за безперервне профілювання та firepit.
- Martin Thwaites, за інтеграцію OpenTelemetry Weaver у Демо.
- Florian Bourgey, за керівництво роботою з перейменування атрибутів.
- Shenoy Pratik, за створення тестового набору перевірки телеметрії.
- Cijo Thomas, за впровадження OpAMP сервера.
- Matthew Wimpelberg, за міграцію генератора навантаження на k6.
- Piotr Kiełkowicz, за розчищення беклогу вразливостей до кінця.
Ми зламали Демо, щоб побудувати щось краще. Сподіваюся, версія 3.0 варта того, щоб оновитися.
Спробуйте та дайте нам знати, що ви знайшли. Відкрийте issue, завітайте на SIG-дзвінок або знайдіть нас у CNCF Slack. Саме так це і працює.