Exportateur Microsoft OpenTelemetry pour Azure Monitor

L’exportateur d’Azure Monitor vous permet d’exporter des données à l’aide du Kit de développement logiciel (SDK) OpenTelemetry et d’envoyer des données de télémétrie à Azure Monitor pour les applications écrites en Python.

| Code sourcePackage (PyPi) | Documentation de référence sur les | API | Documentation produitÉchantillons | Changelog

Prise en main

Installer le package

Installez l’exportateur Microsoft OpenTelemetry pour Azure Monitor avec pip :

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

Prérequis

Pour utiliser ce package, vous devez disposer des conditions suivantes :

Instancier le client

L’interaction avec l’exportateur Azure Monitor commence par un instance de la classe pour le AzureMonitorTraceExporter suivi distribué, AzureMonitorLogExporter la journalisation et AzureMonitorMetricExporter les métriques. Vous aurez besoin d’un connection_string pour instancier l’objet. Recherchez les exemples liés ci-dessous pour une démonstration de la façon de construire l’exportateur à l’aide d’un chaîne de connexion.

Journalisation (expérimentale)

REMARQUE : Le signal de journalisation du AzureMonitorLogExporter est actuellement dans un état EXPERIMENTAL. D’éventuels changements cassants peuvent s’ensuivre à l’avenir.

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

Mesures

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

Traçage

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

Vous pouvez également instancier l’exportateur directement via le constructeur. Dans ce cas, le chaîne de connexion est automatiquement rempli à partir de la variable d’environnementAPPLICATIONINSIGHTS_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()

Concepts clés

Voici quelques-uns des concepts clés de l’exportateur Azure Monitor :

  • OpenTelemetry : OpenTelemetry est un ensemble de bibliothèques utilisées pour collecter et exporter des données de télémétrie (métriques, journaux et traces) à des fins d’analyse afin de comprendre les performances et le comportement de votre logiciel.

  • Instrumentation : l’instrumentation facilite l’appel de l’API OpenTelemetry directement par n’importe quelle application. Une bibliothèque qui active l’observabilité OpenTelemetry pour une autre bibliothèque est appelée bibliothèque d’instrumentation.

  • Journal : Journal fait référence à la capture de la journalisation, des exceptions et des événements.

  • LogRecord : représente un enregistrement de journal émis à partir d’une bibliothèque de journalisation prise en charge.

  • Enregistreur d’événements : convertit un LogRecord en un LogDatalisible et sera envoyé via le KIT de développement logiciel (SDK) à exporter.

  • Fournisseur d’enregistreurs d’événements : fournit un pour la bibliothèque d’instrumentation Logger donnée.

  • LogRecordProcessor : interface permettant de raccorder l’action d’émission d’enregistrement de journal.

  • LoggingHandler : classe de gestionnaire qui écrit les enregistrements de journalisation au format OpenTelemetry à partir de la bibliothèque Python logging standard.

  • AzureMonitorLogExporter : il s’agit de la classe qui est initialisée pour envoyer des données de télémétrie liées à la journalisation à Azure Monitor.

  • Métrique : Metric fait référence à l’enregistrement de mesures brutes avec une agrégation prédéfinie et des jeux d’attributs pour une période dans le temps.

  • Mesure : représente un point de données enregistré à un point dans le temps.

  • Instrument : les instruments sont utilisés pour signaler Measurementdes.

  • Compteur : est Meter chargé de créer Instruments.

  • Fournisseur de compteur : fournit un pour la bibliothèque d’instrumentation Meter donnée.

  • Lecteur de métriques : objet d’implémentation du KIT de développement logiciel (SDK) qui fournit les aspects configurables courants du Kit de développement logiciel (SDK) OpenTelemetry Metrics, tels que la collecte, le vidage et l’arrêt.

  • AzureMonitorMetricExporter : il s’agit de la classe qui est initialisée pour envoyer des données de télémétrie liées aux métriques à Azure Monitor.

  • Trace : trace fait référence au suivi distribué. Une trace distribuée est un ensemble d’événements, déclenchés à la suite d’une seule opération logique, consolidés sur différents composants d’une application. En particulier, une trace peut être considérée comme un graphe acyclique dirigé (DAG) d’étendues, où les arêtes entre les étendues sont définies comme une relation parent/enfant.

  • Étendue : représente une seule opération dans un Trace. Peut être imbriqué pour former une arborescence de traces. Chaque trace contient une étendue racine, qui décrit généralement l’ensemble de l’opération et, éventuellement, un ou plusieurs sous-étendues pour ses sous-opérations.

  • Traceur : responsable de la création Spande s.

  • Fournisseur de suivi : fournit un Tracer pour une utilisation par la bibliothèque d’instrumentation donnée.

  • Processeur d’étendues : un processeur d’étendues autorise les crochets pour les appels de méthode de début et de fin du Span SDK. Pour plus d’informations, suivez le lien.

  • AzureMonitorTraceExporter : il s’agit de la classe qui est initialisée pour envoyer des données de télémétrie liées au suivi à Azure Monitor.

  • Échantillonnage : l’échantillonnage est un mécanisme permettant de contrôler le bruit et la surcharge introduits par OpenTelemetry en réduisant le nombre d’échantillons de traces collectées et envoyées au serveur principal.

  • ApplicationInsightsSampler : échantillonneur spécifique à Application Insights utilisé pour un échantillonnage cohérent entre les kits SDK Application Insights et les kits SDK OpenTelemetry qui envoient des données à Application Insights. Cet échantillonneur DOIT être utilisé chaque fois qu’il AzureMonitorTraceExporter est utilisé.

Pour plus d’informations sur ces ressources, consultez Qu’est-ce qu’Azure Monitor ?.

Configuration

Toutes les options de configuration peuvent être passées par les constructeurs des exportateurs via kwargs. Vous trouverez ci-dessous une liste d’options configurables.

  • connection_string: le chaîne de connexion utilisé pour votre ressource Application Insights.
  • disable_offline_storage: valeur booléenne pour déterminer s’il faut désactiver le stockage des enregistrements de télémétrie ayant échoué pour une nouvelle tentative. La valeur par défaut est False.
  • storage_directory: répertoire de stockage dans lequel stocker les fichiers de nouvelle tentative. La valeur par défaut est <tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.
  • credential: informations d’identification de jeton, telles que ManagedIdentityCredential ou ClientSecretCredential, utilisées pour l’authentification Azure Active Directory (AAD). La valeur par défaut est None. Consultez des exemples pour obtenir des exemples.

Exemples

Journalisation (expérimentale)

REMARQUE : Le signal de journalisation du AzureMonitorLogExporter est actuellement dans un état EXPERIMENTAL. D’éventuels changements cassants peuvent s’ensuivre à l’avenir.

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes, notamment :

Passez en revue le Kit de développement logiciel (SDK) De journalisation OpenTelemetry pour savoir comment utiliser les composants OpenTelemetry pour collecter des journaux.

Exporter Hello World journal

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

Exporter le journal corrélé

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

Exporter le journal des propriétés personnalisées

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

Exporter le journal des exceptions

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

Mesures

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes, notamment :

Passez en revue le Kit de développement logiciel (SDK) Métriques OpenTelemetry pour savoir comment utiliser les composants OpenTelemetry pour collecter des métriques.

Utilisation de l’instrument de métrique

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

Vues personnalisées de métriques

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

Vous trouverez d’autres exemples avec le Kit de développement logiciel (SDK) de métriques Viewsici.

Attributs d’enregistrement de métrique

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

Suivi

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes, notamment :

Passez en revue le Kit de développement logiciel (SDK) De suivi OpenTelemetry pour savoir comment utiliser les composants OpenTelemetry pour collecter des journaux.

Exporter Hello World trace

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

Instrumentation avec bibliothèque de requêtes

OpenTelemetry prend également en charge plusieurs instrumentations qui permettent d’instrumenter avec des bibliothèques tierces.

Pour obtenir la liste des instrumentations disponibles dans OpenTelemetry, consultez la documentation contrib.

Cet exemple montre comment instrumenter avec la bibliothèque de requêtes .

  • Installez le package d’instrumentation des requêtes à l’aide de 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/")

Activation de l’échantillonnage

Vous pouvez activer l’échantillonnage pour limiter la quantité d’enregistrements de télémétrie que vous recevez. Pour activer l’échantillonnage correct dans Application Insights, utilisez le ApplicationInsightsSampler comme indiqué ci-dessous.

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

Comportement de vidage/arrêt

Pour toutes les applications configurées avec le Kit de développement logiciel (SDK) OpenTelemetry et les exportateurs Azure Monitor, la télémétrie est vidée automatiquement à la sortie de l’application. Notez que cela n’inclut pas lorsque l’application se termine brusquement ou se bloque en raison d’une exception non interceptée.

Dépannage

L’exportateur déclenche des exceptions définies dans Azure Core.

Étapes suivantes

Autres exemples de code

Vous trouverez d’autres exemples dans le répertoire d’exemples illustrant des scénarios courants.

Documentation complémentaire

Pour obtenir une documentation plus complète sur le service Azure Monitor, consultez la documentation Azure Monitor sur docs.microsoft.com.

Pour obtenir une vue d’ensemble détaillée d’OpenTelemetry, visitez leur page de vue d’ensemble .

Pour obtenir la documentation officielle d’OpenTelemetry Python et pour savoir comment activer d’autres scénarios de télémétrie, visitez le site web officiel d’OpenTelemetry.

Pour plus d’informations sur la distribution OpenTelemetry d’Azure Monitor, qui est un ensemble de composants utiles et préassembtés (l’un d’eux étant ce package actuel) qui activent des scénarios de télémétrie avec Azure Monitor, consultez README.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.