Средство экспорта Microsoft OpenTelemetry для Azure Monitor

Средство экспорта для Azure Monitor позволяет экспортировать данные с помощью пакета SDK OpenTelemetry и отправлять данные телеметрии в Azure Monitor для приложений, написанных на Python.

Исходный код | Пакет (PyPi) | Справочная документация по | APIДокументация по продукту | Образцы | Changelog

Начало работы

Установка пакета

Установите средство экспорта Microsoft OpenTelemetry для Azure Monitor с помощью pip:

pip install azure-monitor-opentelemetry-exporter --pre

Предварительные требования

Для использования этого пакета необходимо:

• Подписка Azure — создайте бесплатную учетную запись.
• Azure Monitor— использование Application Insights
• Пакет SDK OpenTelemetry — пакет SDK OpenTelemetry для Python
• Python 3.7 или более поздней версии — установка Python

Создание экземпляра клиента

Взаимодействие с экспортером Azure Monitor начинается с экземпляра AzureMonitorTraceExporter класса для распределенной трассировки, AzureMonitorLogExporter ведения журнала и AzureMonitorMetricExporter для метрик. Для создания экземпляра объекта потребуется connection_string . Найдите приведенные ниже примеры для демонстрации того, как создать экспортер с помощью строка подключения.

Ведение журнала (экспериментальное)

ПРИМЕЧАНИЕ. Сигнал ведения журнала для AzureMonitorLogExporter в настоящее время находится в экспериментальном состоянии. Возможные критические изменения могут возникнуть в будущем.

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter
exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

Метрики

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

Трассировка

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

Вы также можете создать экземпляр средства экспорта непосредственно с помощью конструктора. В этом случае строка подключения будет автоматически заполнен из переменной APPLICATIONINSIGHTS_CONNECTION_STRING среды.

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter
exporter = AzureMonitorLogExporter()

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter
exporter = AzureMonitorMetricExporter()

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
exporter = AzureMonitorTraceExporter()

Основные понятия

Ниже перечислены некоторые ключевые понятия средства экспорта Azure Monitor.

• OpenTelemetry. OpenTelemetry — это набор библиотек, используемых для сбора и экспорта данных телеметрии (метрики, журналы и трассировки) для анализа, чтобы понять производительность и поведение программного обеспечения.

• Инструментирование. Возможность вызова API OpenTelemetry напрямую любым приложением облегчается инструментированием. Библиотека, которая обеспечивает возможность наблюдения OpenTelemetry для другой библиотеки, называется библиотекой инструментирования.

• Журнал. Журнал — это запись журналов, исключений и событий.

• LogRecord: представляет запись журнала, полученную из поддерживаемой библиотеки ведения журнала.

• Средство ведения журнала: преобразует LogRecord в удобочитаемый LogDataи отправляется через пакет SDK для экспорта.

• Поставщик средства ведения журнала. Предоставляет для данной Logger библиотеки инструментирования.

• LogRecordProcessor: интерфейс для перехвата действия создания записи журнала.

• LoggingHandler: класс обработчика, который записывает записи журнала в формате OpenTelemetry из стандартной библиотеки Python logging .

• AzureMonitorLogExporter. Это класс, инициализируемый для отправки данных телеметрии, связанных с ведением журнала, в Azure Monitor.

• Метрика: Metric относится к записи необработанных измерений с предопределенным агрегированием и наборами атрибутов за определенный период времени.

• Измерение. Представляет точку данных, записанную в определенный момент времени.

• Инструмент: инструменты используются для создания отчетов Measurement.

• Единица измерения: Meter отвечает за создание Instruments.

• Поставщик счетчиков. Предоставляет Meter для данной библиотеки инструментирования.

• Читатель метрик: объект реализации пакета SDK, который предоставляет общие настраиваемые аспекты пакета SDK для метрик OpenTelemetry, такие как сбор, очистка и завершение работы.

• AzureMonitorMetricExporter. Это класс, инициализируемый для отправки данных телеметрии, связанных с метрикой, в Azure Monitor.

• Трассировка. Трассировка относится к распределенной трассировке. Распределенная трассировка — это набор событий, активирующихся в результате одной логической операции, объединенных в различные компоненты приложения. В частности, трассировку можно рассматривать как направленный ациклический граф (DAG) spans, где ребра между диапазонами определяются как отношение "родитель-потомок".

• Span: представляет одну операцию в .Trace Может быть вложенным для формирования дерева трассировки. Каждая трассировка содержит корневой диапазон, который обычно описывает всю операцию и, при необходимости, один или несколько вложенных диапазонов для ее вложенных операций.

• Трассировка: отвечает за создание Span.

• Поставщик трассировки. Предоставляет Tracer для использования заданной библиотекой инструментирования.

• Процессор Span. Обработчик span позволяет использовать обработчики для вызовов начальных и конечных методов пакета SDK Span . Дополнительные сведения см. по ссылке.

• AzureMonitorTraceExporter. Это класс, инициализируемый для отправки данных телеметрии, связанных с трассировкой, в Azure Monitor.

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

• ApplicationInsightsSampler: специальный выборщик Application Insights, используемый для согласованной выборки в пакетах SDK для Application Insights и пакетах SDK на основе OpenTelemetry, отправляемых в Application Insights. Этот образец должен использоваться при каждом AzureMonitorTraceExporter использовании.

Дополнительные сведения об этих ресурсах см. в статье Что такое Azure Monitor?.

Конфигурация

Все параметры конфигурации могут передаваться через конструкторы экспортеров через kwargs. Ниже приведен список настраиваемых параметров.

• connection_string: строка подключения, используемый для ресурса Application Insights.
• disable_offline_storage: логическое значение, определяющее, следует ли отключить хранение неудачных записей телеметрии для повторных попыток. По умолчанию — False.
• storage_directory: каталог хранения, в котором хранятся файлы повторных попыток. По умолчанию — <tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.
• credential: учетные данные маркера, такие как ManagedIdentityCredential или ClientSecretCredential, используемые для проверки подлинности Azure Active Directory (AAD). Значение по умолчанию — None (Нет). Примеры см. в примерах .

Примеры

Ведение журнала (экспериментальное)

ПРИМЕЧАНИЕ. Сигнал ведения журнала для AzureMonitorLogExporter в настоящее время находится в экспериментальном состоянии. Возможные критические изменения могут возникнуть в будущем.

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач, в том числе:

• Экспорт записи журнала
• Экспорт коррелированных записей журнала
• Экспорт записи журнала с пользовательскими свойствами
• Экспорт записи журнала исключений

Ознакомьтесь с пакетом SDK для ведения журнала OpenTelemetry , чтобы узнать, как использовать компоненты OpenTelemetry для сбора журналов.

Экспорт журнала Hello World

"""
An example to show an application using Opentelemetry logging sdk. Logging calls to the standard Python
logging library are tracked and telemetry is exported to application insights with the AzureMonitorLogExporter.
"""
import os
import logging

from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
    set_logger_provider,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
handler = LoggingHandler()

# Attach LoggingHandler to root logger
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.NOTSET)

logger = logging.getLogger(__name__)

logger.warning("Hello World!")

# Telemetry records are flushed automatically upon application exit
# If you would like to flush records manually yourself, you can call force_flush()
logger_provider.force_flush()

Экспорт коррелированного журнала

"""
An example showing how to include context correlation information in logging telemetry.
"""
import os
import logging

from opentelemetry import trace
from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
    set_logger_provider,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.sdk.trace import TracerProvider

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
handler = LoggingHandler()

# Attach LoggingHandler to root logger
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.NOTSET)

logger = logging.getLogger(__name__)

logger.info("INFO: Outside of span")
with tracer.start_as_current_span("foo"):
    logger.warning("WARNING: Inside of span")
logger.error("ERROR: After span")

Экспорт журнала пользовательских свойств

"""
An example showing how to add custom properties to logging telemetry.
"""
import os
import logging

from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
    set_logger_provider,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)

logger_provider.add_log_record_processor(BatchLogRecordProcessor(exporter))
handler = LoggingHandler()

# Attach LoggingHandler to root logger
logging.getLogger().addHandler(handler)
logging.getLogger().setLevel(logging.NOTSET)

logger = logging.getLogger(__name__)

# Custom properties
logger.debug("DEBUG: Debug with properties", extra={"debug": "true"})

Экспорт журнала исключений

"""
An example showing how to export exception telemetry using the AzureMonitorLogExporter.
"""
import os
import logging

from opentelemetry._logs import (
    get_logger_provider,
    set_logger_provider,
)
from opentelemetry.sdk._logs import (
    LoggerProvider,
    LoggingHandler,
)
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor

from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter

set_logger_provider(LoggerProvider())
exporter = AzureMonitorLogExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
get_logger_provider().add_log_record_processor(BatchLogRecordProcessor(exporter))

# Attach LoggingHandler to namespaced logger
handler = LoggingHandler()
logger = logging.getLogger(__name__)
logger.addHandler(handler)
logger.setLevel(logging.NOTSET)

# The following code will generate two pieces of exception telemetry
# that are identical in nature
try:
    val = 1 / 0
    print(val)
except ZeroDivisionError:
    logger.exception("Error: Division by zero")

try:
    val = 1 / 0
    print(val)
except ZeroDivisionError:
    logger.error("Error: Division by zero", stack_info=True, exc_info=True)

Метрики

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач, в том числе:

• Использование различных инструментов метрик
• Настройка выходных метрик с помощью представлений
• Запись инструментов с атрибутами

Ознакомьтесь с пакетом SDK для метрик OpenTelemetry , чтобы узнать, как использовать компоненты OpenTelemetry для сбора метрик.

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

"""
An example to show an application using all instruments in the OpenTelemetry SDK. Metrics created
and recorded using the sdk are tracked and telemetry is exported to application insights with the
AzureMonitorMetricsExporter.
"""
import os
from typing import Iterable

from opentelemetry import metrics
from opentelemetry.metrics import CallbackOptions, Observation
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

# Create a namespaced meter
meter = metrics.get_meter_provider().get_meter("sample")

# Callback functions for observable instruments
def observable_counter_func(options: CallbackOptions) -> Iterable[Observation]:
    yield Observation(1, {})


def observable_up_down_counter_func(
    options: CallbackOptions,
) -> Iterable[Observation]:
    yield Observation(-10, {})


def observable_gauge_func(options: CallbackOptions) -> Iterable[Observation]:
    yield Observation(9, {})

# Counter
counter = meter.create_counter("counter")
counter.add(1)

# Async Counter
observable_counter = meter.create_observable_counter(
    "observable_counter", [observable_counter_func]
)

# UpDownCounter
up_down_counter = meter.create_up_down_counter("up_down_counter")
up_down_counter.add(1)
up_down_counter.add(-5)

# Async UpDownCounter
observable_up_down_counter = meter.create_observable_up_down_counter(
    "observable_up_down_counter", [observable_up_down_counter_func]
)

# Histogram
histogram = meter.create_histogram("histogram")
histogram.record(99.9)

# Async Gauge
gauge = meter.create_observable_gauge("gauge", [observable_gauge_func])

# Upon application exit, one last collection is made and telemetry records are
# flushed automatically. # If you would like to flush records manually yourself,
# you can call force_flush()
meter_provider.force_flush()

Пользовательские представления метрик

"""
This example shows how to customize the metrics that are output by the SDK using Views. Metrics created
and recorded using the sdk are tracked and telemetry is exported to application insights with the
AzureMonitorMetricsExporter.
"""
import os

from opentelemetry import metrics
from opentelemetry.sdk.metrics import Counter, MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.sdk.metrics.view import View

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter.from_connection_string(
    os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
# Create a view matching the counter instrument `my.counter`
# and configure the new name `my.counter.total` for the result metrics stream
change_metric_name_view = View(
    instrument_type=Counter,
    instrument_name="my.counter",
    name="my.counter.total",
)

reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
provider = MeterProvider(
    metric_readers=[
        reader,
    ],
    views=[
        change_metric_name_view,
    ],
)
metrics.set_meter_provider(provider)

meter = metrics.get_meter_provider().get_meter("view-name-change")
my_counter = meter.create_counter("my.counter")
my_counter.add(100)

Дополнительные примеры с пакетом SDK для метрик Views можно найти здесь.

Атрибуты записей метрик

"""
An example to show an application using different attributes with instruments in the OpenTelemetry SDK.
Metrics created and recorded using the sdk are tracked and telemetry is exported to application insights
with the AzureMonitorMetricsExporter.
"""
import os

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader

from azure.monitor.opentelemetry.exporter import AzureMonitorMetricExporter

exporter = AzureMonitorMetricExporter.from_connection_string(
    os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
reader = PeriodicExportingMetricReader(exporter, export_interval_millis=5000)
metrics.set_meter_provider(MeterProvider(metric_readers=[reader]))

attribute_set1 = {
    "key1": "val1"
}
attribute_set2 = {
    "key2": "val2"
}
large_attribute_set = {}
for i in range(20):
    key = "key{}".format(i)
    val = "val{}".format(i)
    large_attribute_set[key] = val

meter = metrics.get_meter_provider().get_meter("sample")

# Counter
counter = meter.create_counter("attr1_counter")
counter.add(1, attribute_set1)

# Counter2
counter2 = meter.create_counter("attr2_counter")
counter2.add(10, attribute_set1)
counter2.add(30, attribute_set2)

# Counter3
counter3 = meter.create_counter("large_attr_counter")
counter3.add(100, attribute_set1)
counter3.add(200, large_attribute_set)

Трассировка

В следующих разделах представлено несколько фрагментов кода, охватывающих некоторые из наиболее распространенных задач, в том числе:

• Экспорт настраиваемого диапазона
• Использование инструментирования для отслеживания библиотеки
• Включение выборки для ограничения объема отправленных данных телеметрии

Ознакомьтесь с пакетом SDK для трассировки OpenTelemetry , чтобы узнать, как использовать компоненты OpenTelemetry для сбора журналов.

Экспорт трассировки Hello World

"""
An example to show an application using Opentelemetry tracing api and sdk. Custom dependencies are
tracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter.
"""
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

tracer_provider = TracerProvider()
trace.set_tracer_provider(tracer_provider)
tracer = trace.get_tracer(__name__)
# This is the exporter that sends data to Application Insights
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

with tracer.start_as_current_span("hello"):
    print("Hello, World!")

# Telemetry records are flushed automatically upon application exit
# If you would like to flush records manually yourself, you can call force_flush()
tracer_provider.force_flush()

Инструментирование с помощью библиотеки запросов

OpenTelemetry также поддерживает несколько инструментов, которые позволяют инструментировать с библиотеками сторонних производителей.

Список инструментов, доступных в OpenTelemetry, см. в документации по contrib.

В этом примере показано, как инструментировать с помощью библиотеки запросов .

• Установите пакет инструментирования запросов с помощью pip install opentelemetry-instrumentation-requests.

"""
An example to show an application instrumented with the OpenTelemetry requests instrumentation.
Calls made with the requests library will be automatically tracked and telemetry is exported to 
application insights with the AzureMonitorTraceExporter.
See more info on the requests instrumentation here:
https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-requests
"""
import os
import requests
from opentelemetry import trace
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

# This line causes your calls made with the requests library to be tracked.
RequestsInstrumentor().instrument()

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

# This request will be traced
response = requests.get(url="https://azure.microsoft.com/")

Включение выборки

Вы можете включить выборку, чтобы ограничить объем получаемых записей телеметрии. Чтобы включить правильную выборку в Application Insights, используйте ApplicationInsightsSampler , как показано ниже.

"""
An example to show an application using the ApplicationInsightsSampler to enable sampling for your telemetry.
Specify a sampling rate for the sampler to limit the amount of telemetry records you receive. Custom dependencies
 are tracked via spans and telemetry is exported to application insights with the AzureMonitorTraceExporter.
"""
import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from azure.monitor.opentelemetry.exporter import (
    ApplicationInsightsSampler,
    AzureMonitorTraceExporter,
)

# Sampler expects a sample rate of between 0 and 1 inclusive
# A rate of 0.75 means approximately 75% of your telemetry will be sent
sampler = ApplicationInsightsSampler(0.75)
trace.set_tracer_provider(TracerProvider(sampler=sampler))
tracer = trace.get_tracer(__name__)
exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
span_processor = BatchSpanProcessor(exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

for i in range(100):
    # Approximately 25% of these spans should be sampled out
    with tracer.start_as_current_span("hello"):
        print("Hello, World!")

Поведение очистки и завершения работы

Для всех приложений, настроенных с помощью пакета SDK OpenTelemetry и средств экспорта Azure Monitor, данные телеметрии автоматически сбрасываются при выходе из приложения. Обратите внимание, что это не относится к моменту внезапного завершения работы приложения или аварийного завершения работы из-за неперехваченного исключения.

Устранение неполадок

Экспортер создает исключения, определенные в Azure Core.

Дальнейшие действия

Больше примеров кода

Дополнительные примеры можно найти в каталоге примеров , демонстрирующих распространенные сценарии.

Дополнительная документация

Более подробную документацию по службе Azure Monitor см. в документации по Azure Monitor по docs.microsoft.com.

Подробный обзор OpenTelemetry см. на странице обзора .

Официальную документацию OpenTelemetry на Python и о том, как включить другие сценарии телеметрии, см. на официальном веб-сайте OpenTelemetry.

Дополнительные сведения о дистрибутиве OpenTelemetry Azure Monitor, который представляет собой пакет полезных предварительно собранных компонентов (один из которых является текущим пакетом), которые позволяют выполнять сценарии телеметрии с помощью Azure Monitor, см. в файле СВЕДЕНИЙ.

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.