Azure Monitor-Erfassungsclientbibliothek für Python– Version 1.0.3

  • Artikel

Die Azure Monitor-Erfassungsclientbibliothek wird verwendet, um benutzerdefinierte Protokolle mithilfe der Protokollerfassungs-API an Azure Monitor zu senden.

Mit dieser Bibliothek können Sie Daten aus praktisch jeder Quelle an unterstützte integrierte Tabellen oder an benutzerdefinierte Tabellen senden, die Sie im Log Analytics-Arbeitsbereich erstellen. Sie können sogar das Schema integrierter Tabellen mit benutzerdefinierten Spalten erweitern.

Ressourcen:

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Monitor Ingestion-Clientbibliothek für Python mit pip:

pip install azure-monitor-ingestion

Erstellen des Clients

Ein authentifizierter Client ist erforderlich, um Protokolle in Azure Monitor hochzuladen. Die Bibliothek enthält sowohl synchrone als auch asynchrone Formen der Clients. Erstellen Sie zur Authentifizierung eine instance einer Tokenanmeldeinformation. Verwenden Sie diese instance, wenn Sie eine LogsIngestionClienterstellen. In den folgenden Beispielen wird DefaultAzureCredential das Paket azure-identity verwendet.

Synchrone Clients

Sehen Sie sich das folgende Beispiel an, das synchrone Clients zum Hochladen von Protokollen erstellt:

import os
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

Asynchrone Clients

Die asynchronen Formen der Client-APIs befinden sich im .aioNamespace -suffixed. Beispiel:

import os
from azure.identity.aio import DefaultAzureCredential
from azure.monitor.ingestion.aio import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

Konfigurieren von Clients für nicht öffentliche Azure-Clouds

Standardmäßig LogsIngestionClient ist für die Verbindung mit der öffentlichen Azure-Cloud konfiguriert. Um eine Verbindung mit nicht öffentlichen Azure-Clouds herzustellen, ist eine zusätzliche Konfiguration erforderlich. Der geeignete Bereich für die Authentifizierung muss mit dem credential_scopes Argument Schlüsselwort (keyword) bereitgestellt werden. Das folgende Beispiel zeigt, wie Sie den Client für die Verbindung mit Azure US Government konfigurieren:

logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"])

Wichtige Begriffe

Datensammlungsendpunkt

Mit Datensammlungsendpunkten (Data Collection Endpoints, DCEs) können Sie Erfassungseinstellungen für Azure Monitor eindeutig konfigurieren. Dieser Artikel bietet eine Übersicht über Datensammlungsendpunkte, einschließlich ihres Inhalts und ihrer Struktur und wie Sie sie erstellen und damit arbeiten können.

Datensammlungsregel

Datensammlungsregeln (Data Collection Rules, DCR) definieren von Azure Monitor gesammelte Daten und geben an, wie und wo diese Daten gesendet oder gespeichert werden sollen. Der REST-API-Aufruf muss eine zu verwendende DCR angeben. Eine einzelne DCR kann mehrere DCRs unterstützen, weshalb Sie eine andere DCR für verschiedene Quellen und Zieltabellen angeben können.

Das DCR muss die Struktur der Eingabedaten und die Struktur der Zieltabelle erkennen. Wenn die beiden nicht übereinstimmen, kann eine Transformation durchgeführt werden, um die Quelldaten so zu konvertieren, dass sie mit der Zieltabelle kompatibel sind. Sie können die Transformation auch verwenden, um Quelldaten zu filtern und andere Berechnungen oder Konvertierungen durchzuführen.

Weitere Informationen finden Sie unter Datensammlungsregeln in Azure Monitor. Ausführliche Informationen zur Struktur eines DCR finden Sie in diesem Artikel . Informationen zum Abrufen einer DCR-ID finden Sie in diesem Tutorial.

Log Analytics-Arbeitsbereichstabellen

Benutzerdefinierte Protokolle können Daten an jede von Ihnen erstellte benutzerdefinierte Tabelle und an bestimmte integrierte Tabellen in Ihrem Log Analytics-Arbeitsbereich senden. Die Zieltabelle muss existieren, bevor Sie Daten an sie senden können. Die folgenden integrierten Tabellen werden derzeit unterstützt:

Abrufen von Protokollen

Die Protokolle, die mit dieser Bibliothek hochgeladen wurden, können mithilfe der Azure Monitor Query-Clientbibliothek abgefragt werden.

Beispiele

Hochladen von benutzerdefinierten Protokollen

Dieses Beispiel zeigt das Hochladen von Protokollen in Azure Monitor.

import os

from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()

client = LogsIngestionClient(endpoint=endpoint, credential=credential, logging_enable=True)

rule_id = os.environ['LOGS_DCR_RULE_ID']
body = [
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer1",
        "AdditionalContext": "context-2"
      },
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer2",
        "AdditionalContext": "context"
      }
    ]

try:
    client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body)
except HttpResponseError as e:
    print(f"Upload failed: {e}")

Hochladen mit benutzerdefinierter Fehlerbehandlung

Um Protokolle mit benutzerdefinierter Fehlerbehandlung hochzuladen, können Sie eine Rückruffunktion an den on_error Parameter der upload -Methode übergeben. Die Rückruffunktion wird für jeden Fehler aufgerufen, der während des Uploads auftritt, und sollte ein Argument erwarten, das einem LogsUploadError -Objekt entspricht. Dieses Objekt enthält den aufgetretenen Fehler und die Liste der Protokolle, die nicht hochgeladen werden konnten.

# Example 1: Collect all logs that failed to upload.
failed_logs = []
def on_error(error):
    print("Log chunk failed to upload with error: ", error.error)
    failed_logs.extend(error.failed_logs)

# Example 2: Ignore all errors.
def on_error_pass(error):
    pass

client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body, on_error=on_error)

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung.

Nächste Schritte

Weitere Informationen zu Azure Monitor finden Sie in der Dokumentation zum Azure Monitor-Dienst.

Beispiele

Die folgenden Codebeispiele zeigen allgemeine Szenarien mit der Azure Monitor-Erfassungsclientbibliothek.

Protokolle der Erfassungsbeispiele

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. Weitere Informationen finden Sie unter 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 mit unserer CLA tun.

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 Kommentare haben.