Esportazione di Microsoft OpenTelemetry per Monitoraggio di Azure

L'esportazione per Monitoraggio di Azure consente di esportare i dati usando OpenTelemetry SDK e inviare dati di telemetria a Monitoraggio di Azure per le applicazioni scritte in Python.

Codice | sorgentePacchetto (PyPi) | Documentazione di | riferimento sulle APIDocumentazione | del prodottoCampioni | Changelog

Introduzione

Installare il pacchetto

Installare l'esportazione di Microsoft OpenTelemetry per Monitoraggio di Azure con pip:

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

Prerequisiti

Per usare questo pacchetto, è necessario disporre di:

Creare un'istanza del client

L'interazione con l'esportazione di monitoraggio di Azure inizia con un'istanza della classe per la AzureMonitorTraceExporter traccia distribuita, AzureMonitorLogExporter per la registrazione e AzureMonitorMetricExporter per le metriche. È necessario un connection_string per creare un'istanza dell'oggetto. Trovare gli esempi collegati di seguito per la dimostrazione su come costruire l'esportazione usando un stringa di connessione.

Registrazione (sperimentale)

NOTA: il segnale di registrazione per l'oggetto AzureMonitorLogExporter è attualmente in uno stato SPERIMENTALE. Le possibili modifiche di rilievo potrebbero verificarsi in futuro.

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

Metriche

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

Traccia

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

È anche possibile creare un'istanza dell'esportazione direttamente tramite il costruttore. In questo caso, la stringa di connessione verrà popolata automaticamente dalla APPLICATIONINSIGHTS_CONNECTION_STRING variabile di ambiente.

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

Concetti chiave

Alcuni dei concetti principali per l'esportazione di monitoraggio di Azure includono:

  • OpenTelemetry: OpenTelemetry è un set di librerie usate per raccogliere ed esportare dati di telemetria (metriche, log e tracce) per l'analisi per comprendere le prestazioni e il comportamento del software.

  • Strumentazione: la possibilità di chiamare l'API OpenTelemetry direttamente da qualsiasi applicazione è facilitata dalla strumentazione. Una libreria che abilita l'osservabilità openTelemetry per un'altra libreria viene chiamata libreria di strumentazione.

  • Log: log fa riferimento all'acquisizione della registrazione, dell'eccezione e degli eventi.

  • LogRecord: rappresenta un record di log generato da una libreria di registrazione supportata.

  • Logger: converte un oggetto LogRecord in un oggetto leggibile LogDatae verrà eseguito il push tramite l'SDK da esportare.

  • Provider logger: fornisce un oggetto Logger per la libreria di strumentazione specificata.

  • LogRecordProcessor: interfaccia per collegare l'azione di emissione del record di log.

  • LoggingHandler: classe del gestore che scrive i record di registrazione in formato OpenTelemetry dalla libreria Python logging standard.

  • AzureMonitorLogExporter: questa è la classe inizializzata per inviare i dati di telemetria correlati alla registrazione a Monitoraggio di Azure.

  • Metrica: Metric fa riferimento alla registrazione di misurazioni non elaborate con aggregazioni predefinite e set di attributi per un periodo di tempo.

  • Misurazione: rappresenta un punto dati registrato in un momento.

  • Strumento: gli strumenti vengono usati per segnalare Measurements.

  • Contatore: l'oggetto Meter è responsabile della creazione Instrumentsdi .

  • Provider di contatori: fornisce un Meter oggetto per la libreria di strumentazione specificata.

  • Lettore metriche: un oggetto di implementazione sdk che fornisce gli aspetti configurabili comuni dell'SDK delle metriche OpenTelemetry, ad esempio raccolta, scaricamento e arresto.

  • AzureMonitorMetricExporter: questa è la classe inizializzata per inviare dati di telemetria correlati alle metriche a Monitoraggio di Azure.

  • Traccia: la traccia fa riferimento alla traccia distribuita. Una traccia distribuita è un set di eventi, attivato come risultato di un'unica operazione logica, consolidata tra vari componenti di un'applicazione. In particolare, una traccia può essere considerata come un grafico acyclic diretto (DAG) di Spans, dove i bordi tra span sono definiti come relazione padre/figlio.

  • Intervallo: rappresenta una singola operazione all'interno di un Traceoggetto . Può essere annidato per formare un albero di traccia. Ogni traccia contiene un intervallo radice, che in genere descrive l'intera operazione e, facoltativamente, un numero maggiore di intervalli secondari per le relative operazioni secondarie.

  • Traccia: responsabile della creazione Spandi s.

  • Provider di traccia: fornisce un Tracer oggetto per l'uso dalla libreria di strumentazione specificata.

  • Processore span: un processore di intervallo consente hook per le chiamate al metodo iniziale e finale dell'SDK Span . Per altre informazioni, seguire il collegamento.

  • AzureMonitorTraceExporter: questa è la classe inizializzata per inviare dati di telemetria correlati alla traccia a Monitoraggio di Azure.

  • Campionamento: il campionamento è un meccanismo per controllare il rumore e il sovraccarico introdotto da OpenTelemetry riducendo il numero di campioni di tracce raccolte e inviate al back-end.

  • ApplicationInsightsSampler: sampler specifico di Application Insights usato per il campionamento coerente tra SDK di Application Insights e SDK basati su OpenTelemetry che inviano dati a Application Insights. Questo sampler DEVE essere usato ogni volta AzureMonitorTraceExporter che viene usato.

Per altre informazioni su queste risorse, vedere Informazioni su Monitoraggio di Azure?

Configurazione

Tutte le opzioni di configurazione possono essere passate attraverso i costruttori di esportazioni tramite kwargs. Di seguito è riportato un elenco di opzioni configurabili.

  • connection_string: stringa di connessione usato per la risorsa di Application Insights.
  • disable_offline_storage: valore booleano per determinare se disabilitare l'archiviazione dei record di telemetria non riusciti per i tentativi. Il valore predefinito è False.
  • storage_directory: directory di archiviazione in cui archiviare i file di ripetizione dei tentativi. Il valore predefinito è <tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.
  • credential: credenziali token, ad esempio ManagedIdentityCredential o ClientSecretCredential, usate per l'autenticazione di Azure Active Directory (AAD). Il valore predefinito è Nessuna. Per esempi, vedere esempi .

Esempio

Registrazione (sperimentale)

NOTA: il segnale di registrazione per l'oggetto AzureMonitorLogExporter è attualmente in uno stato SPERIMENTALE. Le possibili modifiche di rilievo potrebbero verificarsi in futuro.

Le sezioni seguenti forniscono diversi frammenti di codice che coprono alcune delle attività più comuni, tra cui:

Esaminare OpenTelemetry Logging SDK per informazioni su come usare i componenti OpenTelemetry per raccogliere i log.

Esportare Hello World log

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

Esporta log correlato

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

Esporta log proprietà personalizzate

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

Esporta log eccezioni

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

Metriche

Le sezioni seguenti forniscono diversi frammenti di codice che coprono alcune delle attività più comuni, tra cui:

Esaminare OpenTelemetry Metrics SDK per informazioni su come usare i componenti OpenTelemetry per raccogliere le metriche.

Utilizzo dello strumento metrica

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

Visualizzazioni personalizzate delle metriche

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

Altri esempi con l'SDK delle metriche Views sono disponibili qui.

Attributi di record delle metriche

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

Traccia

Le sezioni seguenti forniscono diversi frammenti di codice che coprono alcune delle attività più comuni, tra cui:

Esaminare OpenTelemetry Tracing SDK per informazioni su come usare i componenti OpenTelemetry per raccogliere i log.

Esportare Hello World traccia

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

Strumentazione con la libreria delle richieste

OpenTelemetry supporta anche diverse strumentazioni che consentono di instrumentare con librerie di terze parti.

Per un elenco di strumentazioni disponibili in OpenTelemetry, visitare la documentazione di contrib.

In questo esempio viene illustrato come instrumentare con la libreria delle richieste .

  • Installare il pacchetto di strumentazione delle richieste usando 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/")

Abilitazione del campionamento

È possibile abilitare il campionamento per limitare la quantità di record di telemetria ricevuti. Per abilitare il campionamento corretto in Application Insights, usare quanto ApplicationInsightsSampler illustrato di seguito.

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

Comportamento di scaricamento/arresto

Per tutte le applicazioni configurate con OpenTelemetry SDK e gli esportatori di Monitoraggio di Azure, i dati di telemetria vengono scaricati automaticamente all'uscita dall'applicazione. Si noti che questo non include quando l'applicazione termina bruscamente o si arresta in modo anomalo a causa di un'eccezione non rilevata.

Risoluzione dei problemi

L'esportazione genera eccezioni definite in Azure Core.

Passaggi successivi

Altro codice di esempio

Per altre informazioni, vedere altri esempi nella directory degli esempi che illustrano scenari comuni.

Documentazione aggiuntiva

Per una documentazione più completa sul servizio Monitoraggio di Azure, vedere la documentazione di Monitoraggio di Azure in docs.microsoft.com.

Per una panoramica dettagliata di OpenTelemetry, visitare la pagina di panoramica .

Per la documentazione ufficiale di OpenTelemetry Python e come abilitare altri scenari di telemetria, visitare il sito Web openTelemetry ufficiale.

Per altre informazioni sulla distribuzione OpenTelemetry OpenTelemetry di Monitoraggio di Azure, che è un bundle di componenti utili e pre-assemblati (uno dei quali è questo pacchetto corrente) che abilita gli scenari di telemetria con Monitoraggio di Azure, visitare README.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.