IKuznetsov: Новая страница: «В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше прило...»

2025-10-09T19:22:45Z

Новая страница: «В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше прило...»

Новая страница

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

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

=== Определение базовых URL API ===
Подробную информацию о сборке базового '''URL-адреса''' конечной точки '''OTLP''' см. в разделе [[Экспорт с помощью OTLP]]. '''URL-адрес''' должен заканчиваться на <code>/api/v2/otlp</code>.

=== Получение токена доступа API ===
Токен доступа для сбора трассировок, логов и метрик можно создать в разделе [[Токен доступа|Токены доступа]] .

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

== Инструментирование своего приложения ==
1. Используйте [https://pypi.org/project/pip/ pip] для установки пакетов '''OpenTelemetry''' '''SDK''' и '''API'''.
{| class="wikitable"
|pip install opentelemetry-api

pip install opentelemetry-sdk

pip install opentelemetry-exporter-otlp-proto-http
|}
2. Добавьте в свой код следующие импорты.
{| class="wikitable"
|import json

import logging

from opentelemetry.sdk.resources import Resource

<nowiki>#</nowiki> 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

<nowiki>#</nowiki> 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

<nowiki>#</nowiki> 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

<nowiki>#</nowiki> 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''' сразу после запуска приложения. Укажите переменные <code>DT_API_URL</code> и <code>DT_API_TOKEN</code>, а также URL-адрес Ключ-АСТРОМ и токен доступа.
{| class="wikitable"
|# ===== 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 = <nowiki>''</nowiki>

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)

<nowiki>#</nowiki> ===== 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

}

)

)

)

<nowiki>#</nowiki> ===== 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)

<nowiki>#</nowiki> ===== 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)

<nowiki>#</nowiki> Attach OTLP handler to root logger

logging.getLogger().addHandler(handler)
|}
''<u>Расширение данных Ключ-АСТРОМ</u>''

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

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

=== Создание интервалов ===
1. Для создания новых интервалов нам сначала нужен объект трассировки.
{| class="wikitable"
|tracer = get_tracer_provider().get_tracer("my-tracer")
|}
2. С помощью <code>tracer</code> теперь можно создавать и запускать новые интервалы <code>start_as_current_span()</code>.
{| class="wikitable"
|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'''».
* Добавили два атрибута, следуя [https://opentelemetry.io/docs/specs/semconv/general/trace/ семантическому соглашению об именовании], специфичные для действия этого диапазона: информацию о методе '''HTTP''' и версии.

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

=== Собирайте метрики ===
1. Для создания новых метрических инструментов нам сначала нужен объект счетчика.
{| class="wikitable"
|meter = get_meter_provider().get_meter("my-meter", "0.1.2") #TODO Replace with the name of your meter
|}
2. С помощью <code>meter</code> мы теперь можем создавать отдельные инструменты, например, счетчик.
{| class="wikitable"
|counter = meter.create_counter(

name="request_counter",

description="The number of requests we received"

)
|}
3. Теперь мы можем вызвать метод <code>add()</code> для записи новых значений <code>counter</code> с помощью нашего счетчика и сохранения дополнительных атрибутов (например, <code>action.type</code>).
{| class="wikitable"
|attributes = {"action.type": "create"}

counter.add(1, attributes)
|}

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

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

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

=== Извлечение контекста при получении запроса ===
В следующем примере мы извлекаем значение заголовка <code>traceparent</code> и используем метод <code>extract()</code> для извлечения предоставленной контекстной информации <code>TraceContextTextMapPropagator</code>, которую затем передаем <code>start_as_current_span()</code> для продолжения трассировки.
{| class="wikitable"
|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-заголовков''' нашего запроса.

Для этого мы передаём пустой объект в <code>TraceContextTextMapPropagator.inject()</code>, который затем получает необходимое значение заголовка <code>traceparent</code>. Затем мы включаем это значение в вызов нашего [https://pypi.org/project/requests/ запроса] к другой службе.
{| class="wikitable"
|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''' .

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

Ручное внедрение OpenTelemetry в Python-приложение - История изменений

IKuznetsov: Новая страница: «В этом пошаговом руководстве показано, как добавить возможность наблюдения в ваше прило...»