Microsoft OpenTelemetry-exporterare för Azure Monitor

Med exportören för Azure Monitor kan du exportera data med OpenTelemetry SDK och skicka telemetridata till Azure Monitor för program som skrivits i Python.

| KällkodPaket (PyPi) | API-referensdokumentation | Produktdokumentation | Prover | Ändringsloggen

Komma igång

Installera paketet

Installera Microsoft OpenTelemetry-exporteraren för Azure Monitor med pip:

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

Förutsättningar

Om du vill använda det här paketet måste du ha:

• Azure-prenumeration – Skapa ett kostnadsfritt konto
• Azure Monitor – Så här använder du Application Insights
• OpenTelemetry SDK – OpenTelemetry SDK för Python
• Python 3.7 eller senare – Installera Python

Instansiera klienten

Interaktion med Azure Monitor-exporteraren börjar med en instans av AzureMonitorTraceExporter klassen för distribuerad spårning, AzureMonitorLogExporter för loggning och AzureMonitorMetricExporter för mått. Du behöver en connection_string för att instansiera objektet. Se exemplen nedan för demonstration om hur du skapar exportören med hjälp av en anslutningssträng.

Loggning (experimentell)

Obs! Loggningssignalen AzureMonitorLogExporter för är för närvarande i ett EXPERIMENTELLT tillstånd. Möjliga icke-bakåtkompatibla ändringar kan uppstå i framtiden.

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

Mått

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

Spårning

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

Du kan också instansiera exportören direkt via konstruktorn. I det här fallet fylls anslutningssträng automatiskt i från APPLICATIONINSIGHTS_CONNECTION_STRING miljövariabeln.

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

Viktiga begrepp

Några av nyckelbegreppen för Azure Monitor-exportören är:

• OpenTelemetry: OpenTelemetry är en uppsättning bibliotek som används för att samla in och exportera telemetridata (mått, loggar och spårningar) för analys för att förstå programvarans prestanda och beteende.

• Instrumentation: Möjligheten att anropa OpenTelemetry-API:et direkt av alla program underlättas av instrumentation. Ett bibliotek som möjliggör OpenTelemetry-observerbarhet för ett annat bibliotek kallas för ett instrumentationsbibliotek.

• Logg: Logg refererar till insamling av loggning, undantag och händelser.

• LogRecord: Representerar en loggpost som genereras från ett loggningsbibliotek som stöds.

• Loggare: Konverterar en LogRecord till en läsbar LogDataoch push-överförs via SDK:et som ska exporteras.

• Loggningsprovider: Tillhandahåller en Logger för det angivna instrumentationsbiblioteket.

• LogRecordProcessor: Gränssnitt för att koppla loggposten som genererar åtgärden.

• LoggingHandler: En hanterarklass som skriver loggningsposter i OpenTelemetry-format från Python-standardbiblioteket logging .

• AzureMonitorLogExporter: Det här är klassen som initieras för att skicka loggningsrelaterad telemetri till Azure Monitor.

• Mått: Metric refererar till att registrera råa mått med fördefinierad aggregering och uppsättningar av attribut för en tidsperiod.

• Mått: Representerar en datapunkt som registrerats vid en tidpunkt.

• Instrument: Instrument används för att rapportera Measurements.

• Mätare: Meter ansvarar för att skapa Instruments.

• Mätarprovider: Tillhandahåller en Meter för det angivna instrumentationsbiblioteket.

• Måttläsare: Ett SDK-implementeringsobjekt som tillhandahåller vanliga konfigurerbara aspekter av OpenTelemetry Metrics SDK, till exempel insamling, tömning och avstängning.

• AzureMonitorMetricExporter: Det här är klassen som initieras för att skicka måttrelaterad telemetri till Azure Monitor.

• Spårning: Spårning refererar till distribuerad spårning. En distribuerad spårning är en uppsättning händelser som utlöses som ett resultat av en enda logisk åtgärd som konsolideras mellan olika komponenter i ett program. I synnerhet kan en spårning betraktas som en riktad acyklisk graf (DAG) av spann, där kanterna mellan span definieras som överordnad/underordnad relation.

• Span: Representerar en enskild åtgärd i en Trace. Kan kapslas för att bilda ett spårningsträd. Varje spårning innehåller ett rotintervall som vanligtvis beskriver hela åtgärden och, om du vill, en eller flera underintervall för dess underåtgärder.

• Tracer: Ansvarar för att skapa Spans.

• Spårningsprovider: Tillhandahåller en Tracer för användning av det angivna instrumentationsbiblioteket.

• Spännviddsprocessor: En spännviddsprocessor tillåter hookar för SDK:s Span start- och slutmetodanrop. Följ länken för mer information.

• AzureMonitorTraceExporter: Det här är klassen som initieras för att skicka spårningsrelaterad telemetri till Azure Monitor.

• Sampling: Sampling är en mekanism för att styra brus och overhead som introduceras av OpenTelemetry genom att minska antalet prover av spårningar som samlas in och skickas till serverdelen.

• ApplicationInsightsSampler: Application Insights-specifik sampler som används för konsekvent sampling i Application Insights SDK:er och OpenTelemetry-baserade SDK:er som skickar data till Application Insights. Den här provtagaren MÅSTE användas när AzureMonitorTraceExporter den används.

Mer information om dessa resurser finns i Vad är Azure Monitor?.

Konfiguration

Alla konfigurationsalternativ kan skickas via konstruktorerna för exportörer via kwargs. Nedan visas en lista över konfigurerbara alternativ.

• connection_string: Den anslutningssträng som används för application insights-resursen.
• disable_offline_storage: Booleskt värde för att avgöra om du vill inaktivera lagring av misslyckade telemetriposter för återförsök. Standardvärdet är False.
• storage_directory: Lagringskatalog där återförsöksfiler ska lagras. Standardvärdet är <tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>.
• credential: Tokenautentiseringsuppgifter, till exempel ManagedIdentityCredential eller ClientSecretCredential, som används för AAD-autentisering (Azure Active Directory). Standardvärdet är Ingen. Exempel finns i exempel .

Exempel

Loggning (experimentell)

Obs! Loggningssignalen AzureMonitorLogExporter för är för närvarande i ett EXPERIMENTELLT tillstånd. Möjliga icke-bakåtkompatibla ändringar kan uppstå i framtiden.

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste uppgifterna, inklusive:

• Exportera en loggpost
• Exportera korrelerad loggpost
• Exportera loggpost med anpassade egenskaper
• Exportera en undantagsloggpost

Granska OpenTelemetry Logging SDK för att lära dig hur du använder OpenTelemetry-komponenter för att samla in loggar.

Exportera Hello World logg

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

Exportera korrelerad logg

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

Exportera loggen för anpassade egenskaper

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

Exportera undantagslogg

"""
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ått

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste uppgifterna, inklusive:

• Använda olika måttinstrument
• Anpassa utdatamått med vyer
• Registrera instrument med attribut

Granska OpenTelemetry Metrics SDK för att lära dig hur du använder OpenTelemetry-komponenter för att samla in mått.

Användning av måttinstrument

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

Anpassade vyer för mått

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

Fler exempel med mått-SDK Views finns här.

Attribut för måttposter

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

Spårning

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste uppgifterna, inklusive:

• Exportera ett anpassat spann
• Använda en instrumentation för att spåra ett bibliotek
• Aktivera sampling för att begränsa mängden telemetri som skickas

Granska OpenTelemetry Tracing SDK för att lära dig hur du använder OpenTelemetry-komponenter för att samla in loggar.

Exportera Hello World spårning

"""
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 med begärandebibliotek

OpenTelemetry stöder också flera instrumentationer som gör det möjligt att instrumentera med bibliotek från tredje part.

En lista över tillgängliga instrumentationer i OpenTelemetry finns i contrib-dokumentationen.

Det här exemplet visar hur du instrument med begärandebiblioteket .

• Installera instrumentationspaketet för begäranden med pip installera 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/")

Aktivera sampling

Du kan aktivera sampling för att begränsa mängden telemetriposter som du får. Använd enligt nedan för att aktivera korrekt sampling i Application Insights ApplicationInsightsSampler .

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

Beteende för tömning/avstängning

För alla program som har konfigurerats med OpenTelemetry SDK och Azure Monitor-exportörer töms telemetri automatiskt när programmet avslutas. Observera att detta inte inkluderar när programmet slutar plötsligt eller kraschar på grund av ett ohanterad undantag.

Felsökning

Exportören genererar undantag som definierats i Azure Core.

Nästa steg

Mer exempelkod

Mer information finns i exempelkatalogen som visar vanliga scenarier.

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Monitor-tjänsten finns i Azure Monitor-dokumentationen om docs.microsoft.com.

En detaljerad översikt över OpenTelemetry finns på deras översiktssida .

Den officiella OpenTelemetry Python-dokumentationen och hur du aktiverar andra telemetriscenarier finns på den officiella OpenTelemetry-webbplatsen.

Mer information om Azure Monitor OpenTelemetry Distro, som är ett paket med användbara, förmonterade komponenter (en av dem är det aktuella paketet) som aktiverar telemetriscenarier med Azure Monitor, finns i README.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.