Специфікація для референтного застосунку

Мета референсного застосунку — мати стандартизований зразок застосунку, який можна реалізувати всіма мовами, для яких існує SDK OpenTelemetry.

Загальні вимоги

• Реалізації Референсного застосунку належать SIG відповідних мов програмування, що реалізують API та SDK OpenTelemetry. Це гарантує, що застосунок відповідає найкращим практикам екосистеми мови програмування, і ми можемо надати план того, як слід інструментувати застосунок.
• Повинна бути версія застосунку без інструментування та з інструментуванням. Вона буде використана в посібнику «Початок роботи» на opentelemetry.io для переходу від застосунку без OpenTelemetry до повністю інструментованого застосунку.
• Повинна бути специфічна для мови дія CI, яка перевіряє, що застосунок компілюється та працює в обох версіях.
• Застосунок повинен запускатися з інтерфейсу командного рядка.
• Має бути файл Dockerfile для запуску застосунку в контейнерному середовищі.
• Застосунок повинен працювати автономно. Іншими словами, він не може мати жорстких залежностей від будь-якого іншого вмісту репозиторію, що його оточує. Це дозволяє користувачам копіювати код у свій власний проєкт без розплутування управління залежностями.

Вимоги до сервісу

• Застосунок повинен стандартно очікувати HTTP-запити на порту 8080. Порт повинен бути налаштований за допомогою змінної середовища APPLICATION_PORT.
• Для обробки HTTP-запитів слід використовувати бібліотеку, для якої доступна бібліотека інструментування. Застосунок повинен надавати точку доступу /rolldice?rolls=<n> через GET (та, за бажанням, POST) і повертати такі коди статусу HTTP та результати JSON:
  • якщо rolls не встановлено або має дійсне вхідне значення ( позитивне ціле число > 0): код статусу 200 і або одне число від 1 до 6, якщо rolls не встановлено, або 1, або масив з n чисел від 1 до 6, де n є значенням rolls
  • якщо rolls встановлено як недійсне вхідне значення (не число): код статусу 400 і {"status": "error", "message": "Parameter rolls must be a positive integer"}
  • якщо rolls встановлено як 0 або від’ємне ціле число: код статусу 500 і відсутність виводу JSON. Приклади помилок будуть використані для демонстрації того, як OpenTelemetry може бути використаний для виявлення помилок.
• До точки доступу /rolldice може бути доданий опціональний атрибут player=name.
• Застосунок повинен виводити наступні рядки журналу:
  • повідомлення рівня INFO для кожного HTTP-запиту зі статусом <400
  • повідомлення рівня WARN для кожного HTTP-запиту зі статусом від 400 до 499, включаючи повідомлення, яке буде надіслано в результаті JSON
  • повідомлення рівня ERROR для кожного HTTP-запиту зі статусом вище 499
  • якщо встановлено необовʼязковий атрибут player, повідомлення рівня DEBUG, яке виводить значення player та отримане число
  • якщо необовʼязковий атрибут player не встановлено, повідомлення рівня DEBUG, яке виводить статичне значення anonymous player та згенероване число. Рядки журналу будуть використані для додавання мосту журналу під час інструментування, щоб продемонструвати, як OpenTelemetry може підключатися до наявних фреймворків журналювання.
• Код застосунку повинен бути розділений на два файли:
  • файл app, що містить обробку HTTP-запитів;
  • файл library, що містить реалізацію функції кидання кубика. Назви цих файлів повинні бути ідіоматичними для мови реалізації, наприклад app.js і roll-the-dice.js. Важливим моментом є те, що завдяки розділенню коду файли демонструють, що library залежить тільки від API, а весь код SDK ініціалізується в коді app.
• Обробка помилок для rolls повинна бути розділена наступним чином:
  • app перевіряє, чи визначено rolls, і якщо ні, то встановлює його значення 1.
  • app перевіряє тільки, чи rolls є числом. Якщо так, то викликає функцію для кидання кубика в library. Якщо ні, то виконує обробку помилки з помилкою 400.
  • library перевіряє, чи rolls є додатним числом. Якщо ні, то генерує помилку. app виявляє помилку і відправляє назад помилку 500.
• library повинна мати зовнішню функцію, яка виконує обробку помилок, як описано вище. Потім зовнішня функція виконує наступні дії залежно від значення rolls:
  • rolls == 1: Виконати внутрішню функцію один раз і повернути значення.
  • rolls > 1: Виконати цикл, який викликає внутрішню функцію rolls разів і повернути результати в масиві.
• Внутрішня функція library створює випадкове число від 1 до 6 і повертає це значення.

Вимоги до інструментування

• За можливості, ініціалізація для OpenTelemetry SDK повинна міститися в окремому файлі та імпортуватися в файл app. В іншому випадку вона повинна бути частиною файлу app.
• Загальні детектори ресурсів повинні завантажуватися під час ініціалізації, наприклад для process, container, os, …
• Файл “lib” повинен залежати тільки від API OpenTelemetry.
• Атрибути service.* повинні бути додані через змінні середовища (OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES).
• Інші resource detectors повинні бути додані до ініціалізації SDK.
• Для експорту телеметрії застосунок повинен використовувати експортер для stdout/console та otlp.
• Повинна бути опція для увімкнення діагностичного логування для компонентів OpenTelemetry, якщо це реалізовано, ідеально через OTEL_LOG_LEVEL.
• Повинна бути можливість додати бібліотеку інструментування для використовуваної бібліотеки HTTP. Ця бібліотека інструментування повинна використовувати стабільні семантичні домовленості для HTTP. Віддайте перевагу бібліотеці, яка охоплює більшість сигналів, ідеально, якщо вона має трейси та метрики.
• Якщо бібліотека інструментування недоступна, тільки тоді функція в app, яка обробляє точку доступу/rolldice, інструментується користувачем шляхом додавання відрізку та метрик.
• Повинен бути міст для логу для використовуваного механізму логування, щоб усі журнали автоматично збиралися та експортувалися.
• Для зовнішньої функції в library повинен бути створений відрізок. Відрізок відстежує час роботи функції. Він записує помилку, якщо вона виникає. Він додає атрибути до відрізку, такі як значення rolls, code.*, …
• Для внутрішньої функції в library повинен бути створений відрізок. Відрізок відстежує час роботи функції. Він додає випадкове число, яке він згенерував, як атрибут до відрізку.
• У файлі library повинні бути створені наступні метрики:
  • лічильник викликів зовнішньої функції
  • гістограма розподілу результатів (1-6)
  • індикатор останнього значення rolls