Azure Monitor Opentelemetry Distro-Clientbibliothek für Python – Version 1.1.1

  • Artikel

Die Azure Monitor-Distribution von Opentelemetry Python stellt mehrere installierbare Komponenten für eine Opentelemetry Azure Monitor-Überwachungslösung bereit. Sie können Ihre Python-Anwendungen instrumentieren, um Telemetriedaten über die Azure Monitor-Exporteure zu erfassen und an Azure Monitor zu melden.

Diese Distribution installiert automatisch die folgenden Bibliotheken:

Offiziell unterstützte Instrumentierung

OpenTelemetry-Instrumentierungen ermöglichen die automatische Sammlung von Anforderungen, die von zugrunde liegenden instrumentierten Bibliotheken gesendet werden. Im Folgenden finden Sie eine Liste der OpenTelemetry-Instrumentierungen, die mit der Azure Monitor-Distribution gebündelt sind. Diese Instrumentierungen sind standardmäßig aktiviert. Informationen zum Deaktivieren dieser Instrumentierung finden Sie im Abschnitt Nutzung unten.

Instrumentierung Name der unterstützten Bibliothek Unterstützte Versionen
Azure Core Tracing OpenTelemetry azure_sdk
Django-Instrumentierung von OpenTelemetry Django Link.
FastApi-Instrumentierung von OpenTelemetry fastapi Link.
OpenTelemetry Flask Instrumentation flask Link.
OpenTelemetry Psycopg2 Instrumentierung psycopg2 Link.
Instrumentierung von OpenTelemetry-Anforderungen requests Link.
OpenTelemetry UrlLib Instrumentation urllib All
OpenTelemetry UrlLib3 Instrumentation urllib3 Link.

Wenn Sie Unterstützung für eine andere OpenTelemetry-Instrumentierung hinzufügen möchten, senden Sie eine Featureanforderung. In der Zwischenzeit können Sie die OpenTelemetry-Instrumentierung manuell über die eigenen APIs (d. h. instrument()) in Ihrem Code verwenden. Ein Beispiel finden Sie hier.

Wichtige Begriffe

Dieses Paket bündelt eine Reihe von OpenTelemetry- und Azure Monitor-Komponenten, um die Sammlung und das Senden von Telemetriedaten an Azure Monitor zu ermöglichen. Verwenden Sie für MANUELLE Instrumentierung die configure_azure_monitor -Funktion. DIE AUTOMATISCHE Instrumentierung wird noch nicht unterstützt.

Die OpenTelemetry-Exporteure von Azure Monitor sind die Standard Komponenten, um dies zu erreichen. Sie können die Exporteure und ihre APIs direkt über dieses Paket verwenden. Lesen Sie die Dokumentation des Exporters, um zu verstehen, wie OpenTelemetry- und Azure Monitor-Komponenten beim Aktivieren der Telemetriesammlung und des Exports funktionieren.

Derzeit befinden sich alle in OpenTelemetry verfügbaren Instrumentierungen in einem Betazustand, was bedeutet, dass sie nicht stabil sind und in Zukunft möglicherweise Breaking Changes aufweisen. Es werden Anstrengungen unternommen, diese in einen stabileren Zustand zu bringen.

Erste Schritte

Voraussetzungen

Um dieses Paket verwenden zu können, benötigen Sie Folgendes:

Installieren des Pakets

Installieren Sie die Azure Monitor Opentelemetry-Distro mit pip:

pip install azure-monitor-opentelemetry

Verbrauch

Sie können die configure_azure_monitor Instrumentierung für Ihre App in Azure Monitor einrichten. configure_azure_monitor unterstützt die folgenden optionalen Argumente. Alle übergebenen Parameter haben Vorrang vor allen verwandten Umgebungsvariablen.

Parameter BESCHREIBUNG Umgebungsvariable
connection_string Der Verbindungszeichenfolge für Ihre Application Insights-Ressource. Die Verbindungszeichenfolge wird automatisch aus der Umgebungsvariable APPLICATIONINSIGHTS_CONNECTION_STRING aufgefüllt, wenn sie nicht explizit übergeben wird. APPLICATIONINSIGHTS_CONNECTION_STRING
logger_name Der Name der Python-Protokollierung , unter der Telemetriedaten erfasst werden. N/A
instrumentation_options Ein geschachteltes Wörterbuch, das bestimmt, welche Instrumentierungen aktiviert oder deaktiviert werden sollen. Instrumentierungen werden durch ihre Bibliotheksnamen bezeichnet. Deaktiviert beispielsweise Die Azure Core-Ablaufverfolgung und die Flask-Instrumentierung, {"azure_sdk": {"enabled": False}, "flask": {"enabled": False}, "django": {"enabled": True}} aber Django und die anderen Standardinstrumentierungen sind aktiviert. Die OTEL_PYTHON_DISABLED_INSTRUMENTATIONS unten erläuterte Umgebungsvariable kann auch zum Deaktivieren von Instrumentierungen verwendet werden. N/A

Sie können mit OpenTelemetry-Umgebungsvariablen weiter konfigurieren, z. B.: | Umgebungsvariable | Beschreibung | |-------------|----------------------| | OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Gibt die OpenTelemetry-Ressource an, die Ihrer Anwendung zugeordnet ist. | | OTEL_LOGS_EXPORTER | Wenn auf Nonefestgelegt ist, deaktiviert die Sammlung und den Export von Protokollierungtelemetriedaten. | | OTEL_METRICS_EXPORTER | Wenn auf Nonefestgelegt ist, deaktiviert die Sammlung und den Export von Metriktelemetriedaten. | | OTEL_TRACES_EXPORTER | Wenn auf Nonefestgelegt ist, deaktiviert die Sammlung und den Export von Telemetriedaten der verteilten Ablaufverfolgung. | | OTEL_BLRP_SCHEDULE_DELAY | Gibt das Protokollierungsexportintervall in Millisekunden an. Diese wird standardmäßig auf 5000 festgelegt. | | OTEL_BSP_SCHEDULE_DELAY | Gibt das Exportintervall für verteilte Ablaufverfolgungen in Millisekunden an. Diese wird standardmäßig auf 5000 festgelegt. | | OTEL_TRACES_SAMPLER_ARG | Gibt das Verhältnis der zu beprobenden Telemetriedaten der verteilten Ablaufverfolgung an. Akzeptierte Werte liegen im Bereich [0,1]. Standardmäßig wird 1.0 verwendet, was bedeutet, dass keine Telemetriedaten abgetastet werden. | | OTEL_PYTHON_DISABLED_INSTRUMENTATIONS | Gibt an, welche der unterstützten Instrumentierungen deaktiviert werden sollen. Deaktivierte Instrumentierungen werden nicht als Teil von configure_azure_monitorinstrumentiert. Sie können jedoch weiterhin manuell mit instrument() direkt instrumentiert werden. Akzeptiert eine durch Trennzeichen getrennte Liste von Kleinbuchstaben für Bibliotheksnamen. Legen Sie beispielsweise auf fest "psycopg2,fastapi" , um die Instrumentierung Psycopg2 und FastAPI zu deaktivieren. Standardmäßig wird eine leere Liste verwendet, wodurch alle unterstützten Instrumentierungen aktiviert werden. | | OTEL_EXPERIMENTAL_RESOURCE_DETECTORS | Eine experimentelle OpenTelemetry-Umgebungsvariable, die verwendet wird, um Ressourcendetektoren anzugeben, die zum Generieren von Ressourcenattributen verwendet werden sollen. Dies ist ein experimentelles Feature, und der Name dieser Variablen und ihr Verhalten können sich nicht abwärtskompatibel ändern. Standardmäßig wird "azure_app_service,azure_vm" verwendet, um die Azure-Ressourcendetektoren für Azure App Service und azure-VM zu aktivieren. Um bestimmte Ressourcendetektoren hinzuzufügen oder zu entfernen, legen Sie die Umgebungsvariable entsprechend fest. Weitere Informationen finden Sie in der Dokumentation zum OpenTelemetry-Python-Ressourcendetektor . |

Azure monitor OpenTelemetry Exporterkonfigurationen

Sie können Azure monitor OpenTelemetry-Exporterkonfigurationsparameter direkt an configure_azure_monitorübergeben. Weitere Informationen finden Sie hier unter zusätzliche Konfiguration im Zusammenhang mit dem Export.

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

Beispiele

Hier finden Sie Beispiele, um die Verwendung der oben genannten Konfigurationsoptionen zu veranschaulichen.

Überwachung in Azure Functions

Korrelation der Ablaufverfolgung

Die Nachverfolgen eingehender Anforderungen, die an Ihre in Azure Functions gehostete Python-Anwendung eingehen, werden nicht automatisch mit den Telemetriedaten korreliert, die darin nachverfolgt werden. Sie können die Ablaufverfolgungskorrelation manuell erreichen, indem Sie die TraceContext wie unten gezeigt direkt extrahieren:


import azure.functions as func

from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace
from opentelemetry.propagate import extract

# Configure Azure monitor collection telemetry pipeline
configure_azure_monitor()

def main(req: func.HttpRequest, context) -> func.HttpResponse:
   ...
   # Store current TraceContext in dictionary format
   carrier = {
      "traceparent": context.trace_context.Traceparent,
      "tracestate": context.trace_context.Tracestate,
   }
   tracer = trace.get_tracer(__name__)
   # Start a span using the current context
   with tracer.start_as_current_span(
      "http_trigger_span",
      context=extract(carrier),
   ):
      ...

Protokollierungsprobleme

Der Azure Functions Worker selbst sendet Die Telemetriedaten der Protokollierung selbst, ohne das Azure Monitor SDK zu verwenden (der Aufruf von configure_azure_monitor()). Dies führt möglicherweise zu doppelten Telemetrieeinträgen beim Senden von Protokolltelemetriedaten. Unsere Empfehlung an Kunden besteht darin, nur das SDK zu verwenden, da es viel umfangreichere Telemetriedaten und Features ermöglicht als die integrierte, die vom Azure Functions Worker bereitgestellt wird. Sie können die Azure Functions Telemetrieprotokollierung deaktivieren, indem Sie die Liste der Handler Ihrer Protokollierung löschen.

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

Achten Sie darauf, dass Sie die obigen Aufrufe aufrufen, BEVOR eine Protokollierung oder der Aufruf von configure_azure_monitor() eingerichtet ist.

Sie können die Protokollierung auch über Azure Functions Konfiguration deaktivieren.

v2.x+

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

v1.x

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

Problembehandlung

Der Exporteur löst in Azure Core definierte Ausnahmen aus.

Nächste Schritte

Weitere Informationen finden Sie in der Dokumentation .

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Zusätzliche Dokumentation