Compartir a través de

Biblioteca cliente de distribución de Opentelemetry de Azure Monitor para Python: versión 1.1.1

  • Artículo

La distribución de Azure Monitor de Python de Opentelemetry proporciona varios componentes instalables disponibles para una solución de supervisión de Azure Monitor de Opentelemetry. Permite instrumentar las aplicaciones de Python para capturar y notificar telemetría a Azure Monitor a través de los exportadores de Azure Monitor.

Esta distribución instala automáticamente las siguientes bibliotecas:

Instrumentaciones admitidas oficialmente

Las instrumentaciones openTelemetry permiten la recopilación automática de solicitudes enviadas desde bibliotecas instrumentadas subyacentes. A continuación se muestra una lista de instrumentaciones de OpenTelemetry que se incluyen con la distribución de Azure Monitor. Estas instrumentaciones están habilitadas de forma predeterminada. Consulte la sección Uso siguiente para obtener información sobre cómo no participar en estas instrumentaciones.

Instrumentación Nombre de biblioteca admitido Versiones compatibles
OpenTelemetry de seguimiento principal de Azure azure_sdk
Instrumentación de Django openTelemetry Django vínculo
Instrumentación fastApi de OpenTelemetry fastapi vínculo
Instrumentación de Flask de OpenTelemetry flask vínculo
Instrumentación psycopg2 de OpenTelemetry psycopg2 vínculo
Instrumentación de solicitudes openTelemetry requests vínculo
Instrumentación urllib de OpenTelemetry urllib Todo
Instrumentación de OpenTelemetry UrlLib3 urllib3 vínculo

Si desea agregar compatibilidad con otra instrumentación de OpenTelemetry, envíe una solicitud de característica. Mientras tanto, puede usar manualmente la instrumentación de OpenTelemetry a través de sus propias API (es instrument()decir, ) en el código. Consulte aquí para ver un ejemplo.

Conceptos clave

Este paquete agrupa una serie de componentes de OpenTelemetry y Azure Monitor para habilitar la recopilación y el envío de telemetría a Azure Monitor. Para la instrumentación MANUAL, use la configure_azure_monitor función . Todavía no se admite la instrumentación AUTOMÁTICA.

Los exportadores de OpenTelemetry de Azure Monitor son los principales componentes para hacerlo. Podrá usar los exportadores y sus API directamente a través de este paquete. Vaya a la documentación del exportador para comprender cómo funcionan los componentes de OpenTelemetry y Azure Monitor para habilitar la recopilación y exportación de telemetría.

Actualmente, todas las instrumentaciones disponibles en OpenTelemetry están en estado beta, lo que significa que no son estables y pueden tener cambios importantes en el futuro. Se están realizando esfuerzos para insertarlos en un estado más estable.

Introducción

Requisitos previos

Para usar este paquete, debe tener:

Instalar el paquete

Instale la distribución de Opentelemetry de Azure Monitor con pip:

pip install azure-monitor-opentelemetry

Uso

Puede usar configure_azure_monitor para configurar la instrumentación de la aplicación en Azure Monitor. configure_azure_monitor admite los argumentos opcionales siguientes. Todos los parámetros de paso tienen prioridad sobre cualquier variable de entorno relacionada.

Parámetro Descripción Variable de entorno
connection_string El cadena de conexión del recurso de Application Insights. El cadena de conexión se rellenará automáticamente desde la APPLICATIONINSIGHTS_CONNECTION_STRING variable de entorno si no se pasa explícitamente. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name Nombre del registrador de Python en el que se recopila la telemetría. N/A
instrumentation_options Diccionario anidado que determina qué instrumentaciones habilitar o deshabilitar. Sus nombres de biblioteca hacen referencia a las instrumentaciones. Por ejemplo, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} deshabilitará Azure Core Tracing y la instrumentación de Flask, pero dejará Django y las demás instrumentaciones predeterminadas habilitadas. La OTEL_PYTHON_DISABLED_INSTRUMENTATIONS variable de entorno que se explica a continuación también se puede usar para deshabilitar las instrumentaciones. N/A

Puede configurar más con variables de entorno de OpenTelemetry como: | Variable de entorno | Descripción | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Especifica el recurso OpenTelemetry asociado a la aplicación. | | OTEL_LOGS_EXPORTER | Si se establece en None, deshabilita la recopilación y exportación de la telemetría de registro. | | OTEL_METRICS_EXPORTER | Si se establece en None, deshabilita la recopilación y exportación de telemetría de métricas. | | OTEL_TRACES_EXPORTER | Si se establece en None, deshabilita la recopilación y exportación de telemetría de seguimiento distribuido. | | OTEL_BLRP_SCHEDULE_DELAY | Especifica el intervalo de exportación de registro en milisegundos. Tiene como valor predeterminado 5000. | | OTEL_BSP_SCHEDULE_DELAY | Especifica el intervalo de exportación de seguimiento distribuido en milisegundos. Tiene como valor predeterminado 5000. | | OTEL_TRACES_SAMPLER_ARG | Especifica la proporción de telemetría de seguimiento distribuido que se va a muestrear. Los valores aceptados están en el intervalo [0,1]. El valor predeterminado es 1.0, lo que significa que no se muestrea ninguna telemetría. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Especifica cuál de las instrumentaciones admitidas que se van a deshabilitar. Las instrumentaciones deshabilitadas no se instrumentarán como parte de configure_azure_monitor. Sin embargo, todavía se pueden instrumentar manualmente con instrument() directamente. Acepta una lista separada por comas de nombres de biblioteca en minúsculas. Por ejemplo, establezca en "psycopg2,fastapi" para deshabilitar las instrumentaciones Psycopg2 y FastAPI. El valor predeterminado es una lista vacía, lo que habilita todas las instrumentaciones admitidas. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Variable de entorno de OpenTelemetry experimental que se usa para especificar Los detectores de recursos que se usarán para generar atributos de recursos. Se trata de una característica experimental y el nombre de esta variable y su comportamiento puede cambiar de una manera no compatible con versiones anteriores. El valor predeterminado es "azure_app_service,azure_vm" para habilitar Azure Resource Detectors para Azure App Service y máquina virtual de Azure. Para agregar o quitar detectores de recursos específicos, establezca la variable de entorno en consecuencia. Consulte la documentación del Detector de recursos de Python de OpenTelemetry para obtener más información. |

Configuraciones del exportador de OpenTelemetry de Azure Monitor

Puede pasar los parámetros de configuración del exportador de OpenTelemetry de Azure Monitor directamente a configure_azure_monitor. Consulte la configuración adicional relacionada con la exportación aquí.

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

Ejemplos

Los ejemplos están disponibles aquí para demostrar cómo usar las opciones de configuración anteriores.

Supervisión en Azure Functions

Correlación de seguimiento

Las solicitudes entrantes con seguimiento que llegan a la aplicación de Python hospedada en Azure Functions no se correlacionarán automáticamente con la telemetría que se realiza el seguimiento dentro de ella. Para lograr manualmente la correlación de seguimiento, extraiga directamente como TraceContext se muestra a continuación:


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),
   ):
      ...

Problemas de registro

El propio trabajo de Azure Functions envía telemetría de registro sin el uso del SDK de Azure Monitor (la llamada a configure_azure_monitor()). Esto hará que pueda experimentar entradas de telemetría duplicadas al enviar telemetría de registro. Nuestra recomendación a los clientes es usar únicamente el SDK, ya que permitirá una telemetría y características mucho más enriquecidas que usar la integrada proporcionada por el Azure Functions trabajador. Puede desactivar el registrador de telemetría de Azure Functions borrando la lista de controladores del registrador.

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

Asegúrese de llamar al anterior antes de que se configuren los registradores o la llamada a configure_azure_monitor() .

También puede deshabilitar el registro a través de Azure Functions configuración.

v2.x y posteriores

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

v1.x

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

Solución de problemas

El exportador genera excepciones definidas en Azure Core.

Pasos siguientes

Consulte la documentación para obtener más información .

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Documentación adicional