Libreria client di inserimento di Monitoraggio di Azure per Python - versione 1.0.3

  • Articolo

La libreria client di inserimento di Monitoraggio di Azure viene usata per inviare log personalizzati a Monitoraggio di Azure usando l'API di inserimento log.

Questa libreria consente di inviare dati da praticamente qualsiasi origine a tabelle predefinite supportate o a tabelle personalizzate create nell'area di lavoro Log Analytics. È anche possibile aggiungere colonne personalizzate per estendere lo schema delle tabelle predefinite.

Risorse:

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client di inserimento di Monitoraggio di Azure per Python con pip:

pip install azure-monitor-ingestion

Creare il client

Per caricare i log in Monitoraggio di Azure è necessario un client autenticato. La libreria include sia forme sincrone che asincrone dei client. Per eseguire l'autenticazione, creare un'istanza di una credenziale del token. Usare tale istanza durante la creazione di un oggetto LogsIngestionClient. Gli esempi seguenti usano DefaultAzureCredential il pacchetto azure-identity .

Client sincroni

Si consideri l'esempio seguente, che crea client sincroni per il caricamento dei log:

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)

Client asincroni

Le forme asincrone delle API client si trovano nello .aiospazio dei nomi -suffisso. Ad esempio:

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)

Configurare i client per cloud di Azure non pubblici

Per impostazione predefinita, LogsIngestionClient è configurato per la connessione al cloud di Azure pubblico. Per connettersi a cloud di Azure non pubblici, è necessaria una configurazione aggiuntiva. L'ambito appropriato per l'autenticazione deve essere fornito usando l'argomento credential_scopes della parola chiave . L'esempio seguente illustra come configurare il client per la connessione ad Azure US Government:

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

Concetti chiave

Endpoint di raccolta dati

Gli endpoint di raccolta dati consentono di configurare in modo univoco le impostazioni di inserimento per Monitoraggio di Azure. Questo articolo offre una panoramica degli endpoint di raccolta dati, inclusi il contenuto e la struttura e come è possibile crearli e usarli.

Regola di raccolta dati

Le regole di raccolta dati definiscono i dati raccolti da Monitoraggio di Azure e specificano come e dove devono essere inviati o archiviati i dati. La chiamata API REST deve specificare un DCR da usare. Un singolo controller di dominio può supportare più controller di dominio, quindi è possibile specificare un record di dominio diverso per origini e tabelle di destinazione diverse.

Il DCR deve comprendere la struttura dei dati di input e la struttura della tabella di destinazione. Se i due elementi non corrispondono, può usare una trasformazione per convertire i dati di origine in modo che corrispondano alla tabella di destinazione. È anche possibile usare la trasformazione per filtrare i dati di origine ed eseguire qualsiasi altro calcolo o conversione.

Per altre informazioni, vedere Regole di raccolta dati in Monitoraggio di Azure e vedere questo articolo per informazioni dettagliate sulla struttura di un DCR. Per informazioni su come recuperare un ID DCR, vedere questa esercitazione.

Tabelle dell'area di lavoro Log Analytics

I log personalizzati possono inviare dati a qualsiasi tabella personalizzata creata e a determinate tabelle predefinite nell'area di lavoro Log Analytics. Prima di poter inviare dati, è necessario che la tabella di destinazione esista. Le tabelle predefinite seguenti sono attualmente supportate:

Recupero dei log

I log caricati usando questa libreria possono essere sottoposti a query usando la libreria client di query di Monitoraggio di Azure .

Esempio

Caricare log personalizzati

Questo esempio mostra il caricamento dei log in Monitoraggio di Azure.

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

Caricamento con gestione degli errori personalizzata

Per caricare i log con la gestione degli errori personalizzata, è possibile passare una funzione di callback al on_error parametro del upload metodo . La funzione di callback viene chiamata per ogni errore che si verifica durante il caricamento e deve prevedere un argomento che corrisponde a un LogsUploadError oggetto . Questo oggetto contiene l'errore rilevato e l'elenco dei log che non sono stati caricati.

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

Risoluzione dei problemi

Per informazioni dettagliate sulla diagnosi di vari scenari di errore, vedere la guida alla risoluzione dei problemi.

Passaggi successivi

Per altre informazioni su Monitoraggio di Azure, vedere la documentazione del servizio Monitoraggio di Azure.

Esempi

Gli esempi di codice seguenti illustrano scenari comuni con la libreria client di inserimento di Monitoraggio di Azure.

Esempi di inserimento dei log

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, visitare 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. È necessario eseguire questa operazione una sola volta in tutti i repository usando l'interfaccia della riga di comando.

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) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.