Exportador de Microsoft OpenTelemetry para Azure Monitor

El exportador de Azure Monitor permite exportar datos mediante el SDK de OpenTelemetry y enviar datos de telemetría a Azure Monitor para aplicaciones escritas en Python.

Código | fuentePaquete (PyPi) | Documentación | de referencia de API | Documentación del productoMuestras | Changelog

Introducción

Instalar el paquete

Instale el exportador de Microsoft OpenTelemetry para Azure Monitor con pip:

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

Requisitos previos

Para usar este paquete, debe tener:

• Una suscripción de Azure (cree una cuenta gratuita).
• Azure Monitor: uso de Application Insights
• SDK de OpenTelemetry: SDK de OpenTelemetry para Python
• Python 3.7 o posterior: instalación de Python

Creación de una instancia del cliente

La interacción con el exportador de Azure Monitor comienza con una instancia de la clase para el AzureMonitorTraceExporter seguimiento distribuido, AzureMonitorLogExporter para el registro y AzureMonitorMetricExporter para las métricas. Necesitará un connection_string para crear una instancia del objeto. Busque los ejemplos vinculados a continuación para la demostración sobre cómo construir el exportador mediante un cadena de conexión.

Registro (experimental)

NOTA: La señal de registro de está AzureMonitorLogExporter actualmente en un estado EXPERIMENTAL. Los posibles cambios importantes pueden producirse en el futuro.

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

Métricas

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

Seguimiento

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

También puede crear instancias del exportador directamente a través del constructor . En este caso, el cadena de conexión se rellenará automáticamente desde la APPLICATIONINSIGHTS_CONNECTION_STRING variable de entorno.

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()

Conceptos clave

Algunos de los conceptos clave para el exportador de Azure Monitor son:

• OpenTelemetry: OpenTelemetry es un conjunto de bibliotecas que se usan para recopilar y exportar datos de telemetría (métricas, registros y seguimientos) para el análisis con el fin de comprender el rendimiento y el comportamiento del software.

• Instrumentación: la instrumentación facilita la capacidad de llamar directamente a la API de OpenTelemetry mediante cualquier aplicación. Una biblioteca que habilita la observabilidad de OpenTelemetry para otra biblioteca se denomina biblioteca de instrumentación.

• Registro: el registro hace referencia a la captura de registros, excepciones y eventos.

• LogRecord: representa un registro emitido desde una biblioteca de registro compatible.

• Registrador: convierte en LogRecord un objeto legible LogDatay se insertará a través del SDK que se va a exportar.

• Proveedor de registrador: proporciona un Logger para la biblioteca de instrumentación especificada.

• LogRecordProcessor: interfaz para enlazar la acción de emisión del registro de registro.

• LoggingHandler: una clase de controlador que escribe registros de registro en formato OpenTelemetry desde la biblioteca estándar de Python logging .

• AzureMonitorLogExporter: esta es la clase que se inicializa para enviar telemetría relacionada con el registro a Azure Monitor.

• Métrica: Metric hace referencia a la grabación de medidas sin procesar con agregación predefinida y conjuntos de atributos durante un período de tiempo.

• Medida: representa un punto de datos registrado en un momento dado.

• Instrumento: los instrumentos se utilizan para informar Measurementde s.

• Medidor: Meter es responsable de crear Instruments.

• Proveedor de medidores: proporciona un Meter para la biblioteca de instrumentación especificada.

• Lector de métricas: un objeto de implementación del SDK que proporciona los aspectos configurables comunes del SDK de métricas de OpenTelemetry, como la recopilación, el vaciado y el apagado.

• AzureMonitorMetricExporter: esta es la clase que se inicializa para enviar telemetría relacionada con métricas a Azure Monitor.

• Seguimiento: seguimiento hace referencia al seguimiento distribuido. Un seguimiento distribuido es un conjunto de eventos, desencadenados como resultado de una única operación lógica, consolidada en varios componentes de una aplicación. En concreto, un seguimiento se puede considerar como un gráfico acíclico dirigido (DAG) de intervalos, donde los bordes entre intervalos se definen como relación primaria/secundaria.

• Intervalo: representa una sola operación dentro de .Trace Se puede anidar para formar un árbol de seguimiento. Cada seguimiento contiene un intervalo raíz, que normalmente describe toda la operación y, opcionalmente, uno o varios sub spans para sus suboperaciones secundarias.

• Tracer: responsable de la creación Spande s.

• Proveedor de seguimiento: proporciona un Tracer objeto para que lo use la biblioteca de instrumentación especificada.

• Procesador de intervalos: un procesador de intervalos permite enlaces para las invocaciones de método inicial y final del Span SDK. Siga el vínculo para obtener más información.

• AzureMonitorTraceExporter: esta es la clase que se inicializa para enviar telemetría relacionada con el seguimiento a Azure Monitor.

• Muestreo: el muestreo es un mecanismo para controlar el ruido y la sobrecarga introducidos por OpenTelemetry al reducir el número de muestras de seguimientos recopilados y enviados al back-end.

• ApplicationInsightsSampler: sampler específico de Application Insights que se usa para el muestreo coherente entre los SDK de Application Insights y los SDK basados en OpenTelemetry que envían datos a Application Insights. Este sampler DEBE usarse siempre que AzureMonitorTraceExporter se use.

Para más información sobre estos recursos, consulte ¿Qué es Azure Monitor?.

Configuración

Todas las opciones de configuración se pueden pasar a través de los constructores de exportadores a través kwargsde . A continuación se muestra una lista de opciones configurables.

• connection_string: el cadena de conexión usado para el recurso de Application Insights.
• disable_offline_storage: valor booleano para determinar si se deshabilita el almacenamiento de registros de telemetría con errores para el reintento. Tiene como valor predeterminado False.
• storage_directory: directorio de almacenamiento en el que se van a almacenar los archivos de reintento. Tiene como valor predeterminado <tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.
• credential: credencial de token, como ManagedIdentityCredential o ClientSecretCredential, que se usa para la autenticación de Azure Active Directory (AAD). El valor predeterminado es None. Consulte ejemplos para obtener ejemplos.

Ejemplos

Registro (experimental)

NOTA: La señal de registro de está AzureMonitorLogExporter actualmente en un estado EXPERIMENTAL. Los posibles cambios importantes pueden producirse en el futuro.

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes, entre las que se incluyen:

• Exportación de un registro
• Exportación de registros correlacionados
• Exportación de registros con propiedades personalizadas
• Exportación de un registro de excepciones

Revise el SDK de registro de OpenTelemetry para obtener información sobre cómo usar componentes de OpenTelemetry para recopilar registros.

Exportar registro de Hola mundo

"""
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()

Exportar registro correlacionado

"""
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")

Exportar registro de propiedades personalizadas

"""
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"})

Exportar registro de excepciones

"""
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)

Métricas

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes, entre las que se incluyen:

• Uso de diferentes instrumentos de métricas
• Personalización de métricas de salida con vistas
• Instrumentos de grabación con atributos

Revise el SDK de métricas de OpenTelemetry para obtener información sobre cómo usar componentes de OpenTelemetry para recopilar métricas.

Uso del instrumento de métrica

"""
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()

Vistas personalizadas de métricas

"""
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)

Puede encontrar más ejemplos con el SDK de métricas Viewsaquí.

Atributos de registro de métricas

"""
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)

Seguimiento

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas más comunes, entre las que se incluyen:

• Exportación de un intervalo personalizado
• Uso de una instrumentación para realizar un seguimiento de una biblioteca
• Habilitación del muestreo para limitar la cantidad de telemetría enviada

Revise el SDK de seguimiento de OpenTelemetry para obtener información sobre cómo usar componentes de OpenTelemetry para recopilar registros.

Exportar seguimiento de Hola mundo

"""
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()

Instrumentación con biblioteca de solicitudes

OpenTelemetry también admite varias instrumentaciones que permiten instrumentar con bibliotecas de terceros.

Para obtener una lista de las instrumentaciones disponibles en OpenTelemetry, visite la documentación de contrib.

En este ejemplo se muestra cómo instrumentar con la biblioteca de solicitudes .

• Instale el paquete de instrumentación de solicitudes mediante 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/")

Habilitación del muestreo

Puede habilitar el muestreo para limitar la cantidad de registros de telemetría que recibe. Para habilitar el muestreo correcto en Application Insights, use como ApplicationInsightsSampler se muestra a continuación.

"""
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!")

Comportamiento de vaciado y apagado

Para todas las aplicaciones configuradas con el SDK de OpenTelemetry y los exportadores de Azure Monitor, la telemetría se vacía automáticamente al salir de la aplicación. Tenga en cuenta que esto no incluye cuando la aplicación finaliza abruptamente o se bloquea debido a una excepción no detectada.

Solución de problemas

El exportador genera excepciones definidas en Azure Core.

Pasos siguientes

Más código de ejemplo

Busque más ejemplos en el directorio de ejemplos que muestran escenarios comunes.

Documentación adicional

Para obtener documentación más amplia sobre el servicio Azure Monitor, consulte la documentación de Azure Monitor sobre docs.microsoft.com.

Para obtener información general detallada sobre OpenTelemetry, visite su página de información general .

Para obtener la documentación oficial de Python de OpenTelemetry y cómo habilitar otros escenarios de telemetría, visite el sitio web oficial de OpenTelemetry.

Para más información sobre la distribución de OpenTelemetry de Azure Monitor, que es una agrupación de componentes útiles y preensamblados (uno de ellos es este paquete actual) que habilitan escenarios de telemetría con Azure Monitor, visite el archivo LÉAME.

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.