Ручное внедрение OpenTelemetry в Python-приложение

В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше приложение Python с помощью библиотек и инструментов OpenTelemetry Python.

Получение данных для доступа к Ключ-АСТРОМ

Определение базовых URL API

Подробную информацию о сборке базового URL-адреса конечной точки OTLP см. в разделе Экспорт с помощью OTLP. URL-адрес должен заканчиваться на /api/v2/otlp.

Получение токена доступа API

Токен доступа для сбора трассировок, логов и метрик можно создать в разделе Токены доступа .

Экспорт с помощью OTLP содержит более подробную информацию о формате и необходимых областях доступа.

Инструментирование своего приложения

1. Используйте pip для установки пакетов OpenTelemetry SDK и API.

pip install opentelemetry-api pip install opentelemetry-sdk pip install opentelemetry-exporter-otlp-proto-http

2. Добавьте в свой код следующие импорты.

import json import logging from opentelemetry.sdk.resources import Resource # Import exporters from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter # Trace imports from opentelemetry.trace import set_tracer_provider, get_tracer_provider from opentelemetry.sdk.trace import TracerProvider, sampling from opentelemetry.sdk.trace.export import BatchSpanProcessor # Metric imports from opentelemetry import metrics as metrics from opentelemetry.sdk.metrics.export import (     AggregationTemporality,     PeriodicExportingMetricReader, ) from opentelemetry.sdk.metrics import MeterProvider, Counter, UpDownCounter, Histogram, ObservableCounter, ObservableUpDownCounter from opentelemetry.metrics import set_meter_provider, get_meter_provider # Logs import from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler from opentelemetry.sdk._logs.export import BatchLogRecordProcessor from opentelemetry._logs import set_logger_provider

3. Добавьте следующий код в последовательность запуска, чтобы инициализировать OpenTelemetry сразу после запуска приложения. Укажите переменные DT_API_URL и DT_API_TOKEN, а также URL-адрес Ключ-АСТРОМ и токен доступа.

# ===== GENERAL SETUP ===== DT_API_URL = "" DT_API_TOKEN = "" merged = dict() for name in ["dt_metadata_e617c525669e072eebe3d0f08212e8f2.json", "/var/lib/astromkey/enrichment/dt_metadata.json", "/var/lib/astromkey/enrichment/dt_host_metadata.json"]:   try:     data = ''     with open(name) as f:       data = json.load(f if name.startswith("/var") else open(f.read()))       merged.update(data)   except:     pass merged.update({   "service.name": "python-quickstart", #TODO Replace with the name of your application   "service.version": "1.0.1", #TODO Replace with the version of your application }) resource = Resource.create(merged) # ===== TRACING SETUP ===== tracer_provider = TracerProvider(sampler=sampling.ALWAYS_ON, resource=resource) set_tracer_provider(tracer_provider) tracer_provider.add_span_processor(   BatchSpanProcessor(     OTLPSpanExporter(       endpoint = DT_API_URL + "/v1/traces",       headers = {         "Authorization": "Api-Token " + DT_API_TOKEN       }     )   ) ) # ===== METRIC SETUP ===== exporter = OTLPMetricExporter(   endpoint = DT_API_URL + "/v1/metrics",   headers = {"Authorization": "Api-Token " + DT_API_TOKEN},   preferred_temporality = {     Counter: AggregationTemporality.DELTA,     UpDownCounter: AggregationTemporality.CUMULATIVE,     Histogram: AggregationTemporality.DELTA,     ObservableCounter: AggregationTemporality.DELTA,     ObservableUpDownCounter: AggregationTemporality.CUMULATIVE,   } ) reader = PeriodicExportingMetricReader(exporter) provider = MeterProvider(metric_readers=[reader], resource=resource) set_meter_provider(provider) # ===== LOG SETUP ===== logger_provider = LoggerProvider(resource=resource) set_logger_provider(logger_provider) logger_provider.add_log_record_processor(   BatchLogRecordProcessor(OTLPLogExporter(     endpoint = DT_API_URL + "/v1/logs", headers = {"Authorization": "Api-Token " + DT_API_TOKEN}   )) ) handler = LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider) # Attach OTLP handler to root logger logging.getLogger().addHandler(handler)

Расширение данных Ключ-АСТРОМ

Операции чтения файлов, анализирующие файлы dt_metadata в примере кода, пытаются прочитать файлы данных ЕдиногоАгента, чтобы обогатить запрос OTLP и гарантировать, что вся соответствующая информация о топологии доступна в Ключ-АСТРОМ.

Добавление телеметрических сигналов вручную (необязательно)

Создание интервалов

1. Для создания новых интервалов нам сначала нужен объект трассировки.

tracer = get_tracer_provider().get_tracer("my-tracer")

2. С помощью tracer теперь можно создавать и запускать новые интервалы start_as_current_span().

with tracer.start_as_current_span("Call to /myendpoint") as span:     span.set_attribute("http.method", "GET")     span.set_attribute("net.protocol.version", "1.1")     #TODO your code goes here

В приведенном выше коде мы:

• Создали новый диапазон и назовите его «Call to /myendpoint».
• Добавили два атрибута, следуя семантическому соглашению об именовании, специфичные для действия этого диапазона: информацию о методе HTTP и версии.

Этот промежуток будет автоматически установлен как текущий и активный до тех пор, пока поток выполнения не выйдет за пределы области действия текущего метода. Последующие промежутки автоматически станут дочерними.

Собирайте метрики

1. Для создания новых метрических инструментов нам сначала нужен объект счетчика.

meter = get_meter_provider().get_meter("my-meter", "0.1.2") #TODO Replace with the name of your meter

2. С помощью meter мы теперь можем создавать отдельные инструменты, например, счетчик.

counter = meter.create_counter(   name="request_counter",   description="The number of requests we received" )

3. Теперь мы можем вызвать метод add() для записи новых значений counter с помощью нашего счетчика и сохранения дополнительных атрибутов (например, action.type).

attributes = {"action.type": "create"} counter.add(1, attributes)

Подключение логов

Используя переменную logging, инициализированную в разделе «Настройка», мы можем напрямую подключаться к настроенной конечной точке OpenTelemetry в Ключ-АСТРОМ.

Обеспечение распространения контекста

Распространение контекста особенно важно, когда задействованы сетевые вызовы (например, REST).

Если вы используете автоматическое инструментирование и ваши сетевые библиотеки также им охватываются, то это будет автоматически реализовано библиотеками инструментирования. В противном случае ваш код должен это учитывать.

Извлечение контекста при получении запроса

В следующем примере мы извлекаем значение заголовка traceparent и используем метод extract() для извлечения предоставленной контекстной информации TraceContextTextMapPropagator, которую затем передаем start_as_current_span() для продолжения трассировки.

from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator traceparent = request.headers.get_all("traceparent") carrier = {"traceparent": traceparent} ctx = TraceContextTextMapPropagator().extract(carrier) with tracer.start_as_current_span("my-span", context=ctx) as span:     span.set_attribute("my-key-1", "my-value-1")

Внедрение контекста при отправке запросов

В следующем примере мы отправляем REST-запрос к другой службе и предоставляем наш существующий контекст как часть HTTP-заголовков нашего запроса.

Для этого мы передаём пустой объект в TraceContextTextMapPropagator.inject(), который затем получает необходимое значение заголовка traceparent. Затем мы включаем это значение в вызов нашего запроса к другой службе.

from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator with tracer.start_as_current_span("my-span") as span:     span.set_attribute("my-key-1", "my-value-1")     try:         carrier = {}         TraceContextTextMapPropagator().inject(carrier)         header = {"traceparent": carrier["traceparent"]}         response = requests.get(url, headers=header)     except Exception as e:         pass

Настройка сбора данных в соответствии с требованиями конфиденциальности (необязательно)

Хотя Ключ-АСТРОМ автоматически собирает все атрибуты OpenTelemetry, в веб-интерфейсе Ключ-АСТРОМ сохраняются и отображаются только значения атрибутов, указанные в списке разрешенных. Это предотвращает случайное сохранение персональных данных, позволяя вам соблюдать требования к конфиденциальности и контролировать объем хранимых данных мониторинга.

Чтобы просматривать пользовательские атрибуты, необходимо сначала разрешить их использование в веб-интерфейсе Ключ-АСТРОМ.

Проверка загрузки данных в Ключ-АСТРОМ

После завершения инструментирования вашего приложения выполните несколько тестовых действий для создания и отправки демонстрационных трассировок, метрик и логов, а также проверьте, что они были правильно загружены в Ключ-АСТРОМ.

Чтобы сделать это для трассировок, перейдите в раздел Трассировки и выберите вкладку Распределенные трассировки. Если вы используете ЕдиныйАгент, выберите PurePaths .

Для просмотра метрик и логов перейдите в раздел Метрики или Логов или Логи и события.