Англійська для OpenTelemetry

«Звідки походить затримка» неможливо відповісти без правильного словника в розподіленій системі, тому що затримка може бути в будь-якій з десятків послуг - сліди, проміжки і інструменти - це слова, які дозволяють команді вказувати на точний стрибок, який повільний.

Ключовий словник

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

** Обсяг ** — єдина одиниця роботи у межах траси, що представляє одну дію (наприклад, запит до бази даних або виклик API) з часом початку, тривалістю і метаданими, вкладеними для показу ієрархії викликів. “Розмах запиту бази даних займає 300 з 400 мілісекунд трасування — саме на цьому нам слід зосередитися, а не на API-шлюзі.”

** Інструментація ** — код (ручний або автоматичний), який генерує діапазони і сліди, коли служба обробляє запити, фактичний механізм, за допомогою якого збираються дані спостережливості. “Ми додали інструменти до платіжної служби останнього спринту - до того, це був чорний ящик в кожному сліді, просто прогалина без видимості того, що він робить.”

** Контекстне розповсюдження ** — передавання ідентифікаторів трасування між службами під час потоку запиту, отже, об’ єми, створені різними службами, можна буде правильно поєднати у єдиний трасування, замість того, щоб з’ являтися як непов’ язані фрагменти.

• “Трасування переривається на межі черги, оскільки контекстне поширення не вбудовано для асинхронних завдань — діапазони до і після черги показано як два від’ єднаних трасування замість одного.” *

** Collector ** — компонент OpenTelemetry, який отримує, обробляє і експортує дані телеметричної зйомки з інструментальних служб до сервера (наприклад, Jaeger або Datadog) для зберігання і візуалізації. “Траси перестали з’ являтися на панелі управління, оскільки збірник не працював протягом години — служби все ще генерують лінії, вони просто не знаходять місця для зберігання.”

Звичайні фрази

• Чи можемо ми підняти слід для цього запиту і побачити, який проміжок часу є повільним?»
• Чи є ця служба інструментованою, чи це все ще чорна скринька в сліді?»
• Чи є контекстне поширення насправді підключене через цю межу послуги?
• Чи є колектор здоровим, чи це тому, що слідів немає?»
• «Що ж таке цей камінь?»

Приклади висловлювань

Діагностика затримки за допомогою сліду: “Дивлячись на слід, запит витрачає 50 мс в API-шлюзі і 20 мс в аутентифікації, але потім 800 мс в одному проміжку для рекомендаційної служби - це очевидно, куди йде бюджет затримки.”

Пояснення прогалини видимості: “Ми не можемо побачити, що відбувається в старій службі розрахунків під час інцидентів, тому що вона не інструментована - кожен слід просто показує прогалину, де ця служба повинна бути, тому ми зневаджуємо сліпо для цього переходу.”

Опис пошкодженого сліду під час ретро: “Трасування фрагментувалося на частини, оскільки для черги повідомлень не було реалізовано контекстне поширення — розділи з обох сторін черги виглядали як два непов’ язаних запити замість одного неперервного трасування.”

Професійні поради

• Використовуйте span, а не « step » або « part », коли вказуєте на певну повільну операцію у трасі — це точна одиниця вимірювання інструментів спостережливості, і використання її точно дасть вам швидшу відповідь від того, хто читає трасу.
• Прапор відсутності ** інструментації ** безпосередньо як прогалина, а не просто “ми не маємо видимості” - назва конкретної неінструментованої служби говорить команді точно, що виправити.
• Спочатку перевірте ** контекстне розповсюдження **, якщо слід виглядає фрагментованим через асинхронну межу (чека, фонові завдання) — це найпоширеніша причина розриву слідів замість правильного зв’ язку.
• Перевірте, чи є ** колектор ** у належному стані, перш ніж припустити, що само приладдя пошкоджено — відсутній слід може означати, що жодного сліду не було створено, або що слід було створено, але втрачено під час пересилання.

Практичні вправи

1. Напишіть речення, у якому буде пояснено зв’ язок між слідом і діапазоном.
2. Пояснити, що робить контекстне поширення і чому воно важливе для кордонів служб.
3. Опишете, як ви діагностуєте, чи є відсутність даних трасування проблемою інструментів чи проблемою збірника.

Розширення вашого словника спостережливості: акцент на нюанси

Основні концепції OpenTelemetry - сліди, розмахи і інструменти - відносно прості для розуміння. Однак, справжнє ефективне спілкування в команді розробників, зосереджених на спостережливості, вимагає більше, ніж просто знати терміни; це про те, щоб використовувати їх точно і з розумінням тонких відмінностей у значенні, що рідні англомовні люди часто приймають за обов’язкове. Для не-рідних розробників, це може бути значною перешкодою, що призводить до непорозумінь або неефективних обговорень. Давайте розглянемо, як уточнити вашу фразу при описі цих концепцій - особливо зосереджуючись на ясності і точності.

Одна поширена проблема виникає під час перегляду коду. Уявіть, що ви отримуєте коментар на кшталт: “Цій ділянці бракує інструментів”. Хоча це технічно вірно, але в ньому бракує контексту. Кориснішою відповіддю може бути: « Чи можете ви додати інструментальну метрику до цього проміжку часу, яка відстежує тривалість запиту на базу даних? » Це допоможе нам зрозуміти, чи є якісь проблеми з продуктивністю. “Зауважте додану специфіку - ми не просто вказуємо на недолік (“відсутність інструментації”), але пропонуємо * що * слід додати і * чому *. Аналогічно, в обговореннях Slack про нову функцію, заява «Ми повинні інструментувати цю службу» є неясною. Краще було б сказати: « Давайте додамо до цієї служби діапазони OpenTelemetry, щоб стежити за затримкою запитів і кількістю помилок під час впровадження змін ». Другий приклад надає негайний контекст і пояснює мету інструментів. Ключовим тут є перехід за межі простих визначення і продемонструвати розуміння того, як інструменти сприяють ширшій стратегії спостережливості.

Інша область, де нюанс має значення, це в описах PR. Загальний опис, наприклад, « Додано OpenTelemetry », просто не надає достатньої інформації для рецензентів. Замість цього, націляйтеся на щось на зразок: « Реалізовані OpenTelemetry розширює службу user_authentication для захоплення часу обробки запитів і ідентифікації потенційних проблем з продуктивністю. Це включає інструменти для тривалості запиту бази даних і затримки виклику API. Ми використовуємо стратегію вибірки, щоб зменшити накладні витрати. “Цей докладний опис дозволяє рецензентам швидко оцінити вплив змін і зрозуміти, як це відповідає цілям спостережливості команди. Це також негайно сигналізує, що ви розглянули потенційні вузли і проактивно додали відповідні показники.

Нарешті, пам’ятайте про активний проти пасивного голосу. Хоча обидва прийнятні, використання активного голосу зазвичай призводить до яснішого і більш короткого спілкування. Замість того, щоб сказати « Цей код створив діапазони », скажіть « Цей код створює діапазони ». Це невелика різниця, але послідовне застосування цього принципу може значно поліпшити якість і ясність вашого технічного тексту.

# Example OpenTelemetry Python Instrumentation - Logging Span Attributes

import os
from opentelemetry import trace
from opentelemetry.propagate import tracecontext
import logging

tracer = trace.get_tracer(__name__)

def my_function(input_data):
    ctx = tracecontext.get(os.environ.get("OPENTELEMETRY_TRACEID", "default-traceid")) # Get trace ID from environment if available
    span = tracer.start_as_current("my_function")
    try:
        logging.info(f"Input data: {input_data}")
        result = input_data * 2
        logging.info(f"Result: {result}")
        span.set_attribute("input_value", input_data)
        span.set_attribute("output_value", result)
    except Exception as e:
        span.record_exception(e)
    finally:
        span.end()

if __name__ == "__main__":
    my_function(10)