Інструментування

Інструментування — це процес додавання коду спостереження до вашого застосунку.

Якщо ви інструментуєте застосунок, вам потрібно використовувати OpenTelemetry SDK для вашої мови програмування. Потім ви будете використовувати SDK для ініціалізації OpenTelemetry та API для інструментування вашого коду. Це буде генерувати телеметрію з вашого застосунку та будь-якої бібліотеки, яку ви встановили, що також містить інструментування.

Якщо ви інструментуєте бібліотеку, встановіть лише пакет OpenTelemetry API для вашої мови програмування. Ваша бібліотека не буде генерувати телеметрію самостійно. Вона буде генерувати телеметрію лише тоді, коли буде частиною застосунку, що використовує OpenTelemetry SDK. Для отримання додаткової інформації про інструментування бібліотек дивіться Бібліотеки.

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

Налаштування

Спочатку переконайтеся, що у вас встановлені пакунки API та SDK:

pip install opentelemetry-api
pip install opentelemetry-sdk

Трейси

Отримання Tracer

Щоб почати трасування, вам потрібно ініціалізувати TracerProvider і за бажанням стандартно встановити його як глобальний.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    BatchSpanProcessor,
    ConsoleSpanExporter,
)

provider = TracerProvider()
processor = BatchSpanProcessor(ConsoleSpanExporter())
provider.add_span_processor(processor)

# Sets the global default tracer provider
trace.set_tracer_provider(provider)

# Creates a tracer from the global tracer provider
tracer = trace.get_tracer("my.tracer.name")

Створення відрізків

Щоб створити відрізок, зазвичай потрібно почати його як поточний відрізок.

def do_work():
    with tracer.start_as_current_span("span-name") as span:
        # do some work that 'span' will track
        print("doing some work...")
        # When the 'with' block goes out of scope, 'span' is closed for you

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

Створення вкладених відрізків

Якщо у вас є окрема під-операція, яку ви хочете відстежити як частину іншої, ви можете створити відрізки для представлення відносин:

def do_work():
    with tracer.start_as_current_span("parent") as parent:
        # do some work that 'parent' tracks
        print("doing some work...")
        # Create a nested span to track nested work
        with tracer.start_as_current_span("child") as child:
            # do some work that 'child' tracks
            print("doing some nested work...")
            # the nested span is closed when it's out of scope

        # This span is also closed when it goes out of scope

Коли ви переглядаєте відрізки в інструменті візуалізації трейсів, child буде відстежуватися як вкладений відрізок у parent.

Створення відрізків з декораторами

Зазвичай один відрізок відстежує виконання всієї функції. У такому випадку можна використовувати декоратор для зменшення коду:

@tracer.start_as_current_span("do_work")
def do_work():
    print("doing some work...")

Використання декоратора еквівалентне створенню відрізка всередині do_work() і його завершенню після завершення do_work().

Щоб використовувати декоратор, у вас повинен бути екземпляр tracer, доступний глобально для вашої функції.

Отримання поточного відрізка

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

from opentelemetry import trace

current_span = trace.get_current_span()
# enrich 'current_span' with some information

Додавання атрибутів до відрізка

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

from opentelemetry import trace

current_span = trace.get_current_span()

current_span.set_attribute("operation.value", 1)
current_span.set_attribute("operation.name", "Saying hello!")
current_span.set_attribute("operation.other-stuff", [1, 2, 3])

Додавання семантичних атрибутів

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

Щоб використовувати семантичні атрибути в Python, переконайтеся, що у вас встановлений пакунок семантичних домовленостей:

pip install opentelemetry-semantic-conventions

Потім ви можете використовувати його в коді:

from opentelemetry import trace
from opentelemetry.semconv.trace import SpanAttributes

// ...

current_span = trace.get_current_span()
current_span.set_attribute(SpanAttributes.HTTP_METHOD, "GET")
current_span.set_attribute(SpanAttributes.HTTP_URL, "https://opentelemetry.io/")

Додавання подій

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

from opentelemetry import trace

current_span = trace.get_current_span()

current_span.add_event("Gonna try it!")

# Do the thing

current_span.add_event("Did it!")

Додавання посилань

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

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("span-1"):
    # Do something that 'span-1' tracks.
    ctx = trace.get_current_span().get_span_context()
    link_from_span_1 = trace.Link(ctx)

with tracer.start_as_current_span("span-2", links=[link_from_span_1]):
    # Do something that 'span-2' tracks.
    # The link in 'span-2' is causally associated it with the 'span-1',
    # but it is not a child span.
    pass

Встановлення статусу відрізка

Статус можна встановити на Відрізок, зазвичай використовується для вказівки, що Відрізок не завершився успішно — Error. Стандартно, всі відрізки мають статус Unset, що означає, що відрізок завершився без помилок. Статус Ok зарезервований для випадків, коли потрібно явно позначити відрізок як успішний, а не залишати його зі статусом Unset (тобто “без помилок”).

Статус можна встановити в будь-який час до завершення відрізка.

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

current_span = trace.get_current_span()

try:
    # something that might fail
except:
    current_span.set_status(Status(StatusCode.ERROR))

Запис помилок у відрізки

Доброю ідеєю може бути запис помилок, коли вони трапляються. Рекомендується робити це разом з встановленням статусу відрізка.

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

current_span = trace.get_current_span()

try:
    # something that might fail

# Consider catching a more specific exception in your code
except Exception as ex:
    current_span.set_status(Status(StatusCode.ERROR))
    current_span.record_exception(ex)

Зміна стандартного формату розповсюдження

Стандартно OpenTelemetry Python використовуватиме такі формати розповсюдження:

• W3C Trace Context
• W3C Baggage

Якщо вам потрібно змінити стандартні налаштування, ви можете зробити це або через змінні середовища, або в коді:

Використання змінних середовища

Ви можете встановити змінну середовища OTEL_PROPAGATORS зі списком, розділеним комами. Прийняті значення:

• "tracecontext": W3C Trace Context
• "baggage": W3C Baggage
• "b3": B3 Single
• "b3multi": B3 Multi
• "jaeger": Jaeger
• "xray": AWS X-Ray (сторонній)
• "ottrace": OT Trace (сторонній)
• "none": Немає автоматично налаштованого розповсюджувача.

Стандартна конфігурація еквівалентна до OTEL_PROPAGATORS="tracecontext,baggage".

Використання SDK API

Альтернативно, ви можете змінити формат у коді.

Наприклад, якщо вам потрібно використовувати формат розповсюдження Zipkin B3, ви можете встановити пакунок B3:

pip install opentelemetry-propagator-b3

А потім встановити розповсюджувач B3 у вашому коді ініціалізації трасування:

from opentelemetry.propagate import set_global_textmap
from opentelemetry.propagators.b3 import B3Format

set_global_textmap(B3Format())

Зверніть увагу, що змінні середовища переважатимуть над тим, що налаштовано в коді.

Додатково

• Концепції трасування
• Специфікація трасування
• Документація API трасування Python
• Документація SDK трасування Python

Метрики

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

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import (
    ConsoleMetricExporter,
    PeriodicExportingMetricReader,
)

metric_reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
provider = MeterProvider(metric_readers=[metric_reader])

# Sets the global default meter provider
metrics.set_meter_provider(provider)

# Creates a meter from the global meter provider
meter = metrics.get_meter("my.meter.name")

Створення та використання синхронних інструментів

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

Спочатку створіть свій інструмент. Інструменти зазвичай створюються один раз на рівні модуля або класу, а потім використовуються разом з бізнес-логікою. Цей приклад використовує інструмент Counter для підрахунку кількості виконаних робіт:

work_counter = meter.create_counter(
    "work.counter", unit="1", description="Counts the amount of work done"
)

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

def do_work(work_item):
    # count the work being doing
    work_counter.add(1, {"work.type": work_item.work_type})
    print("doing some work...")

Створення та використання асинхронних інструментів

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

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

from typing import Iterable
from opentelemetry.metrics import CallbackOptions, Observation


def scrape_config_versions(options: CallbackOptions) -> Iterable[Observation]:
    r = requests.get(
        "http://configserver/version_metadata", timeout=options.timeout_millis / 10**3
    )
    for metadata in r.json():
        yield Observation(
            metadata["version_num"], {"config.name": metadata["version_num"]}
        )

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

meter.create_observable_gauge(
    "config.version",
    callbacks=[scrape_config_versions],
    description="The active config version for each configuration",
)

Додатково

• Концепції метрик
• Специфікація метрик
• Документація API метрик Python
• Документація SDK метрик Python

Логи

API та SDK для логів наразі розробляються. Щоб почати збір логів, вам потрібно ініціалізувати LoggerProvider і за бажанням встановити його стандартно як глобальний. Потім використовуйте вбудований модуль ведення логів Python для створення записів журналу, які OpenTelemetry може обробити.

import logging
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, ConsoleLogExporter
from opentelemetry._logs import set_logger_provider, get_logger

provider = LoggerProvider()
processor = BatchLogRecordProcessor(ConsoleLogExporter())
provider.add_log_record_processor(processor)
# Встановлює глобального стандартного постачальника логів
set_logger_provider(provider)

logger = get_logger(__name__)

handler = LoggingHandler(level=logging.INFO, logger_provider=provider)
logging.basicConfig(handlers=[handler], level=logging.INFO)

logging.info("This is an OpenTelemetry log record!")

Додатково

• Концепції Логів
• Специфікація Логів
• Документація API Logs Python
• Документація SDK Logs Python

Наступні кроки

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