Клиентская библиотека дистрибутива Opentelemetry Azure Monitor для Python версии 1.1.1

  • Статья

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

Этот дистрибутив автоматически устанавливает следующие библиотеки:

Официально поддерживаемые инструменты

Инструментирования OpenTelemetry позволяют автоматически собирать запросы, отправляемые из базовых инструментированных библиотек. Ниже приведен список инструментов OpenTelemetry, которые входят в состав дистрибутива Azure Monitor. Эти инструменты включены по умолчанию. Сведения о том, как отказаться от этих инструментов, см. в разделе Использование ниже.

Инструментирование Имя поддерживаемой библиотеки Поддерживаемые версии
Трассировка Azure Core OpenTelemetry azure_sdk
OpenTelemetry Django Instrumentation Джанго ссылка
OpenTelemetry FastApi Instrumentation fastapi ссылка
Инструментирование OpenTelemetry Flask Колбу ссылка
Инструментирование OpenTelemetry Psycopg2 psycopg2 ссылка
Инструментирование запросов OpenTelemetry requests ссылка
Инструментирование UrlLib OpenTelemetry urllib Все
Инструментирование OpenTelemetry UrlLib3 urllib3 ссылка

Если вы хотите добавить поддержку другого инструментирования OpenTelemetry, отправьте запрос на функцию. В то же время инструментирование OpenTelemetry можно использовать вручную с помощью собственных API (т. е. instrument()) в коде. Пример см. в этой статье.

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

Этот пакет содержит ряд компонентов OpenTelemetry и Azure Monitor для сбора и отправки данных телеметрии в Azure Monitor. Для инструментирования ВРУЧНУЮ используйте функцию configure_azure_monitor . Автоматическое инструментирование пока не поддерживается.

Средства экспорта OpenTelemetry в Azure Monitor являются main компонентами для этого. Вы сможете использовать экспортеров и их API непосредственно через этот пакет. Ознакомьтесь с документацией по экспортеру, чтобы понять, как работают компоненты OpenTelemetry и Azure Monitor при включении сбора и экспорта данных телеметрии.

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

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

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

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

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

Установите дистрибутив Opentelemetry Azure Monitor с помощью pip:

pip install azure-monitor-opentelemetry

Использование

Вы можете использовать для configure_azure_monitor настройки инструментирования приложения в Azure Monitor. configure_azure_monitor поддерживает следующие необязательные аргументы. Все передаваемые параметры берут приоритет над любыми связанными переменными среды.

Параметр Описание Переменная среды
connection_string Строка подключения для ресурса Application Insights. Строка подключения будет автоматически заполнен из переменной среды, APPLICATIONINSIGHTS_CONNECTION_STRING если она не передана явным образом. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name Имя средства ведения журнала Python , с помощью которого собираются данные телеметрии. N/A
instrumentation_options Вложенный словарь, определяющий, какие инструменты следует включать или отключать. На инструментарии ссылаются имена библиотек. Например, отключит трассировку Azure Core и инструментирование Flask, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} но не включит Django и другие инструменты по умолчанию. Переменная OTEL_PYTHON_DISABLED_INSTRUMENTATIONS среды, описанная ниже, также может использоваться для отключения инструментирования. N/A

Вы можете настроить дополнительные параметры с помощью переменных среды OpenTelemetry, например | Переменная среды | Описание | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Указывает ресурс OpenTelemetry, связанный с приложением. | | OTEL_LOGS_EXPORTER | Если задано значение None, сбор и экспорт данных телеметрии журнала отключается. | | OTEL_METRICS_EXPORTER | Если задано значение None, сбор и экспорт телеметрии метрик отключается. | | OTEL_TRACES_EXPORTER | Если задано значение None, сбор и экспорт данных телеметрии распределенной трассировки отключается. | | OTEL_BLRP_SCHEDULE_DELAY | Задает интервал экспорта журнала в миллисекундах. По умолчанию — 5000. | | OTEL_BSP_SCHEDULE_DELAY | Задает интервал экспорта распределенной трассировки в миллисекундах. По умолчанию — 5000. | | OTEL_TRACES_SAMPLER_ARG | Указывает соотношение данных телеметрии распределенной трассировки для выборки. Допустимые значения находятся в диапазоне [0,1]. По умолчанию используется значение 1.0, то есть выборка данных телеметрии не выполняется. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Указывает, какие из поддерживаемых инструментов следует отключить. Отключенные инструменты не будут инструментироваться как часть configure_azure_monitor. Однако их можно по-прежнему инструментировать вручную с помощью instrument() напрямую. Принимает разделенный запятыми список имен библиотек в нижнем регистре. Например, установите значение , "psycopg2,fastapi" чтобы отключить инструменты Psycopg2 и FastAPI. По умолчанию используется пустой список, включив все поддерживаемые инструменты. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Экспериментальная переменная среды OpenTelemetry, используемая для указания детекторов ресурсов для создания атрибутов ресурсов. Это экспериментальная функция, и имя этой переменной и ее поведение могут измениться не обратно совместимым способом. По умолчанию используется значение "azure_app_service,azure_vm", чтобы включить детекторы ресурсов Azure для Служба приложений Azure и виртуальной машины Azure. Чтобы добавить или удалить определенные детекторы ресурсов, задайте соответствующую переменную среды. Дополнительные сведения см. в документации по детектору ресурсов Python для OpenTelemetry . |

Конфигурации средства экспорта OpenTelemetry в Azure Monitor

Параметры конфигурации средства экспорта OpenTelemetry в Azure Monitor можно передать непосредственно в configure_azure_monitor. Дополнительные сведения о настройке, связанной с экспортом, см. здесь.

...
configure_azure_monitor(
   connection_string="<your-connection-string>",
   disable_offline_storage=True,
)
...

Примеры

Примеры доступны здесь , чтобы продемонстрировать, как использовать указанные выше параметры конфигурации.

Мониторинг в Функции Azure

Корреляция трассировки

Отслеживаемые входящие запросы, поступающие в приложение Python, размещенное в Функции Azure, не будут автоматически сопоставляться с отслеживаемой в нем телеметрией. Вы можете вручную достичь корреляции трассировки, извлекая TraceContext напрямую, как показано ниже:


import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

Проблемы с ведением журнала

Рабочая роль Функции Azure сама отправляет данные телеметрии журнала без использования пакета SDK azure Monitor (вызов ).configure_azure_monitor() Это приведет к дублированию записей телеметрии при отправке данных телеметрии журнала. Мы рекомендуем клиентам использовать только пакет SDK, так как он обеспечит гораздо больше возможностей телеметрии и функций, чем встроенный пакет, предоставляемый рабочей ролью Функции Azure. Вы можете отключить средство ведения журнала телеметрии Функции Azure, очистив список обработчиков средства ведения журнала.

...
root_logger = logging.getLogger()
for handler in root_logger.handlers[:]:
    root_logger.removeHandler(handler)
...

Не забудьте вызвать указанный выше метод BEFORE для любых средств ведения журнала или вызов настроен configure_azure_monitor() .

Вы также можете отключить ведение журнала с помощью Функции Azure конфигурации.

Версия 2.x+

...
{
  "logging": {
    ...
    "logLevel": {
      "default": "None",
      ...
    }
  }
}
...

Версия 1.x

...
{
  "logger": {
    "categoryFilter": {
      "defaultLevel": "None",
      ...
    }
  }
}
...

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

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

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

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

Участие

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

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

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

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