Bibliothèque de client d’ingestion Azure Monitor pour Python - version 1.0.3

  • Article

La bibliothèque cliente d’ingestion Azure Monitor est utilisée pour envoyer des journaux personnalisés à Azure Monitor à l’aide de l’API Ingestion des journaux.

Cette bibliothèque vous permet d’envoyer des données à partir de pratiquement n’importe quelle source aux tables intégrées prises en charge ou aux tables personnalisées que vous créez dans l’espace de travail Log Analytics. Vous pouvez même étendre le schéma des tables intégrées avec des colonnes personnalisées.

Ressources :

Prise en main

Prérequis

Installer le package

Installez la bibliothèque de client d’ingestion Azure Monitor pour Python avec pip :

pip install azure-monitor-ingestion

Création du client

Un client authentifié est nécessaire pour charger les journaux sur Azure Monitor. La bibliothèque inclut des formes synchrones et asynchrones des clients. Pour vous authentifier, créez une instance des informations d’identification d’un jeton. Utilisez cette instance lors de la création d’un LogsIngestionClient. Les exemples suivants utilisent DefaultAzureCredential à partir du package azure-identity .

Clients synchrones

Prenons l’exemple suivant, qui crée des clients synchrones pour le chargement des journaux :

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)

Clients asynchrones

Les formes asynchrones des API clientes se trouvent dans l’espace .aiode noms -suffixed. Par exemple :

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)

Configurer des clients pour des clouds Azure non publics

Par défaut, LogsIngestionClient est configuré pour se connecter au cloud Azure public. Pour vous connecter à des clouds Azure non publics, une configuration supplémentaire est requise. L’étendue appropriée pour l’authentification doit être fournie à l’aide de l’argument credential_scopes mot clé. L’exemple suivant montre comment configurer le client pour qu’il se connecte à Azure US Government :

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

Concepts clés

Point de terminaison de collecte de données

Les points de terminaison de collecte de données (DCE) vous permettent de configurer de manière unique les paramètres d’ingestion pour Azure Monitor. Cet article fournit une vue d’ensemble des points de terminaison de collecte de données, y compris leur contenu et leur structure, ainsi que la façon dont vous pouvez les créer et les utiliser.

Règle de collecte de données

Les règles de collecte de données (DCR) définissent les données collectées par Azure Monitor et spécifient comment et où ces données doivent être envoyées ou stockées. L’appel de l’API REST doit spécifier une règle de collecte de données à utiliser. Un seul point de terminaison de collecte de données peut prendre en charge plusieurs règles de collecte de données. Vous pouvez donc spécifier une règle de collecte de données différente pour chaque source et chaque table cible.

La règle de collecte de données doit comprendre la structure des données d’entrée et celle de la table cible. Si les deux ne correspondent pas, elle peut utiliser une transformation pour convertir les données sources en fonction de la table cible. Vous pouvez également utiliser la transformation pour filtrer les données sources et effectuer d’autres calculs et conversions.

Pour plus d’informations, consultez Règles de collecte de données dans Azure Monitor et consultez cet article pour plus d’informations sur la structure d’un DCR. Pour plus d’informations sur la récupération d’un ID DCR, consultez ce tutoriel.

Tables d’espace de travail Log Analytics

Les journaux personnalisés peuvent envoyer des données à n’importe quelle table personnalisée créée par vos soins et à certaines tables intégrées de votre espace de travail Log Analytics. La table cible doit déjà exister pour que vous puissiez lui envoyer des données. Les tables intégrées actuellement prises en charge sont les suivantes :

Récupération des journaux

Les journaux qui ont été chargés à l’aide de cette bibliothèque peuvent être interrogés à l’aide de la bibliothèque cliente de requête Azure Monitor .

Exemples

Charger des journaux personnalisés

Cet exemple montre comment charger des journaux dans 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}")

Charger avec gestion des erreurs personnalisée

Pour charger des journaux avec une gestion des erreurs personnalisée, vous pouvez passer une fonction de rappel au on_error paramètre de la upload méthode. La fonction de rappel est appelée pour chaque erreur qui se produit pendant le chargement et doit s’attendre à un argument qui correspond à un LogsUploadError objet. Cet objet contient l’erreur rencontrée et la liste des journaux qui n’ont pas pu être téléchargés.

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

Dépannage

Pour plus d’informations sur le diagnostic des différents scénarios d’échec, consultez notre guide de résolution des problèmes.

Étapes suivantes

Pour en savoir plus sur Azure Monitor, consultez la documentation du service Azure Monitor.

Exemples

Les exemples de code suivants illustrent des scénarios courants avec la bibliothèque cliente d’ingestion Azure Monitor.

Exemples d’ingestion de journaux

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous n’aurez besoin de le faire qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d'informations, consultez la FAQ du Code de conduite ou contactez opencode@microsoft.com pour toute question ou commentaire supplémentaire.