Bibliothèque cliente de requête Azure Monitor pour Python - version 1.2.0

  • Article

La bibliothèque cliente de requête Azure Monitor est utilisée pour exécuter des requêtes en lecture seule sur les deux plateformes de données d’Azure Monitor :

  • Journaux : collecte et organise les données de journal et de performances à partir des ressources supervisées. Les données provenant de différentes sources telles que les journaux de plateforme des services Azure, les données de journal et de performances des agents de machines virtuelles, ainsi que les données d’utilisation et de performances des applications peuvent être consolidées dans un seul espace de travail Azure Log Analytics. Les différents types de données peuvent être analysés ensemble à l’aide de la Langage de requête Kusto.
  • Métriques : collecte des données numériques à partir des ressources surveillées dans une base de données de séries chronologiques. Les métriques sont des valeurs numériques collectées à intervalles réguliers et qui décrivent un certain aspect d’un système à un moment donné. Les métriques sont légères et capables de prendre en charge des scénarios en quasi-temps réel, ce qui les rend utiles pour les alertes et la détection rapide des problèmes.

Ressources :

Prise en main

Prérequis

Installer le package

Installez la bibliothèque cliente de requête Azure Monitor pour Python avec pip :

pip install azure-monitor-query

Création du client

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

Clients synchrones

Prenons l’exemple suivant, qui crée des clients synchrones pour l’interrogation des journaux et des métriques :

from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, MetricsQueryClient

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
metrics_client = MetricsQueryClient(credential)

Clients asynchrones

Les formes asynchrones des API clientes de requête se trouvent dans l’espace .aiode noms -suffixed. Exemple :

from azure.identity.aio import DefaultAzureCredential
from azure.monitor.query.aio import LogsQueryClient, MetricsQueryClient

credential = DefaultAzureCredential()
async_logs_client = LogsQueryClient(credential)
async_metrics_client = MetricsQueryClient(credential)

Configurer des clients pour des clouds Azure non publics

Par défaut, LogsQueryClient et MetricsQueryClient sont configurés pour se connecter au cloud Azure public. Ceux-ci peuvent être configurés pour se connecter à des clouds Azure non publics en passant l’argument correct endpoint : Par exemple :

logs_client = LogsQueryClient(credential, endpoint="https://api.loganalytics.azure.cn/v1")
metrics_client = MetricsQueryClient(credential, endpoint="https://management.chinacloudapi.cn")

Remarque : utilise actuellement MetricsQueryClient le point de terminaison Azure Resource Manager (ARM) pour interroger les métriques. Vous aurez donc besoin du point de terminaison de gestion correspondant pour votre cloud lors de l’utilisation de ce client. Notez que cette limitation pourra faire l'objet de modifications.

exécuter la requête.

Pour obtenir des exemples de requêtes de journaux et de métriques, consultez la section Exemples .

Concepts clés

Limites et limitation du taux de requête des journaux

Le service Log Analytics applique une limitation lorsque le taux de requêtes est trop élevé. Des limites, telles que le nombre maximal de lignes retournées, sont également appliquées aux requêtes Kusto. Pour plus d’informations, consultez API de requête.

Si vous exécutez une requête de journaux de traitement par lots, une requête limitée retourne un LogsQueryError objet. La valeur de cet code objet sera ThrottledError.

Structure des données des métriques

Chaque ensemble de valeurs de métriques est une série chronologique avec les caractéristiques suivantes :

  • L’heure à laquelle la valeur a été collectée
  • Ressource associée à la valeur
  • Un espace de noms qui agit comme une catégorie pour la métrique
  • Un nom de métrique
  • La valeur elle-même
  • Certaines métriques peuvent avoir plusieurs dimensions, comme décrit dans Métriques multidimensionnelles. Les métriques personnalisées peuvent avoir jusqu’à 10 dimensions.

Exemples

Requête Logs

Cet exemple montre comment interroger un espace de travail Log Analytics. Pour gérer la réponse et l’afficher sous forme tabulaire, la bibliothèque pandas est utilisée. Consultez les exemples si vous choisissez de ne pas utiliser pandas.

Spécifier l’intervalle de temps

Le timespan paramètre spécifie la durée pendant laquelle interroger les données. Cette valeur peut être l'une des suivantes :

  • a timedelta
  • a timedelta et une dateheure de début
  • dateheure/date/heure de fin

Exemple :

import os
import pandas as pd
from datetime import datetime, timezone
from azure.monitor.query import LogsQueryClient, LogsQueryStatus
from azure.identity import DefaultAzureCredential
from azure.core.exceptions import HttpResponseError

credential = DefaultAzureCredential()
client = LogsQueryClient(credential)

query = """AppRequests | take 5"""

start_time=datetime(2021, 7, 2, tzinfo=timezone.utc)
end_time=datetime(2021, 7, 4, tzinfo=timezone.utc)

try:
    response = client.query_workspace(
        workspace_id=os.environ['LOG_WORKSPACE_ID'],
        query=query,
        timespan=(start_time, end_time)
        )
    if response.status == LogsQueryStatus.PARTIAL:
        error = response.partial_error
        data = response.partial_data
        print(error)
    elif response.status == LogsQueryStatus.SUCCESS:
        data = response.tables
    for table in data:
        df = pd.DataFrame(data=table.rows, columns=table.columns)
        print(df)
except HttpResponseError as err:
    print("something fatal happened")
    print(err)

Gérer la réponse aux requêtes des journaux

L’API query_workspace retourne un LogsQueryResult objet ou .LogsQueryPartialResult L’API batch_query retourne une liste qui peut contenir des LogsQueryResultobjets , LogsQueryPartialResultet LogsQueryError . Voici une hiérarchie de la réponse :

LogsQueryResult
|---statistics
|---visualization
|---tables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columns
    |---columns_types

LogsQueryPartialResult
|---statistics
|---visualization
|---partial_error (a `LogsQueryError` object)
    |---code
    |---message
    |---details
    |---status
|---partial_data (list of `LogsTable` objects)
    |---name
    |---rows
    |---columns
    |---columns_types

le LogsQueryResult itère directement sur la table par commodité. Par exemple, pour gérer une réponse de requête de journaux avec des tables et l’afficher à l’aide de pandas :

response = client.query(...)
for table in response:
    df = pd.DataFrame(table.rows, columns=[col.name for col in table.columns])

Vous trouverez un exemple complet ici.

De la même façon, pour gérer une réponse de requête de journaux de traitement par lots :

for result in response:
    if result.status == LogsQueryStatus.SUCCESS:
        for table in result:
            df = pd.DataFrame(table.rows, columns=table.columns)
            print(df)

Vous trouverez un exemple complet ici.

Requête des journaux Batch

L’exemple suivant illustre l’envoi de plusieurs requêtes en même temps à l’aide de l’API de requête par lots. Les requêtes peuvent être représentées sous la forme d’une liste d’objets LogsBatchQuery ou d’un dictionnaire. Cet exemple utilise la première approche.

import os
from datetime import timedelta, datetime, timezone
import pandas as pd
from azure.monitor.query import LogsQueryClient, LogsBatchQuery, LogsQueryStatus
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = LogsQueryClient(credential)
requests = [
    LogsBatchQuery(
        query="AzureActivity | summarize count()",
        timespan=timedelta(hours=1),
        workspace_id=os.environ['LOG_WORKSPACE_ID']
    ),
    LogsBatchQuery(
        query= """bad query""",
        timespan=timedelta(days=1),
        workspace_id=os.environ['LOG_WORKSPACE_ID']
    ),
    LogsBatchQuery(
        query= """let Weight = 92233720368547758;
        range x from 1 to 3 step 1
        | summarize percentilesw(x, Weight * 100, 50)""",
        workspace_id=os.environ['LOG_WORKSPACE_ID'],
        timespan=(datetime(2021, 6, 2, tzinfo=timezone.utc), datetime(2021, 6, 5, tzinfo=timezone.utc)), # (start, end)
        include_statistics=True
    ),
]
results = client.query_batch(requests)

for res in results:
    if res.status == LogsQueryStatus.FAILURE:
        # this will be a LogsQueryError
        print(res.message)
    elif res.status == LogsQueryStatus.PARTIAL:
        ## this will be a LogsQueryPartialResult
        print(res.partial_error)
        for table in res.partial_data:
            df = pd.DataFrame(table.rows, columns=table.columns)
            print(df)
    elif res.status == LogsQueryStatus.SUCCESS:
        ## this will be a LogsQueryResult
        table = res.tables[0]
        df = pd.DataFrame(table.rows, columns=table.columns)
        print(df)

Requête des journaux de ressources

L’exemple suivant montre comment interroger des journaux directement à partir d’une ressource Azure sans utiliser d’espace de travail Log Analytics. Ici, la query_resource méthode est utilisée au lieu de query_workspace, et au lieu d’un ID d’espace de travail, un identificateur de ressource Azure est transmis (par exemple /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}).

import os
import pandas as pd
from datetime import timedelta
from azure.monitor.query import LogsQueryClient, LogsQueryStatus
from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential

credential  = DefaultAzureCredential()
client = LogsQueryClient(credential)

query = """AzureActivity | take 5"""

try:
    response = client.query_resource(os.environ['LOGS_RESOURCE_ID'], query, timespan=timedelta(days=1))
    if response.status == LogsQueryStatus.PARTIAL:
        error = response.partial_error
        data = response.partial_data
        print(error)
    elif response.status == LogsQueryStatus.SUCCESS:
        data = response.tables
    for table in data:
        df = pd.DataFrame(data=table.rows, columns=table.columns)
        print(df)
except HttpResponseError as err:
    print("something fatal happened")
    print(err)

Scénarios de requête de journaux avancés

Définir le délai d’expiration de la requête des journaux

L’exemple suivant montre la définition d’un délai d’attente du serveur en secondes. Un délai d’expiration de passerelle est déclenché si la requête prend plus de temps que le délai d’expiration mentionné. La valeur par défaut est de 180 secondes et peut être configurée jusqu’à 10 minutes (600 secondes).

import os
from azure.monitor.query import LogsQueryClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = LogsQueryClient(credential)

response = client.query_workspace(
    os.environ['LOG_WORKSPACE_ID'],
    "range x from 1 to 10000000000 step 1 | count",
    timespan=timedelta(days=1),
    server_timeout=600 # sets the timeout to 10 minutes
    )

Interroger plusieurs espaces de travail

La même requête de journaux peut être exécutée dans plusieurs espaces de travail Log Analytics. En plus de la requête Kusto, les paramètres suivants sont requis :

  • workspace_id - ID du premier espace de travail (principal).
  • additional_workspaces - Liste des espaces de travail, à l’exclusion de l’espace de travail fourni dans le workspace_id paramètre. Les éléments de liste du paramètre peuvent se composer des formats d’identificateur suivants :
    • Noms d’espaces de travail qualifiés
    • ID d’espace de travail
    • ID de ressource Azure

Par exemple, la requête suivante s’exécute dans trois espaces de travail :

client.query_workspace(
    <workspace_id>,
    query,
    timespan=timedelta(days=1),
    additional_workspaces=['<workspace 2>', '<workspace 3>']
    )

Vous trouverez un exemple complet ici.

Inclure des statistiques

Pour obtenir les statistiques d’exécution des requêtes des journaux, telles que la consommation de processeur et de mémoire :

  1. Définissez le paramètre include_statistics sur True.
  2. Accédez au statistics champ à l’intérieur de l’objet LogsQueryResult .

L’exemple suivant imprime l’heure d’exécution de la requête :

query = "AzureActivity | top 10 by TimeGenerated"
result = client.query_workspace(
    <workspace_id>,
    query,
    timespan=timedelta(days=1),
    include_statistics=True
    )

execution_time = result.statistics.get("query", {}).get("executionTime")
print(f"Query execution time: {execution_time}")

Le statistics champ correspond à la réponse JSON brute et sa structure peut varier d’une requête à l’autre dict . Les statistiques se trouvent dans la query propriété . Exemple :

{
  "query": {
    "executionTime": 0.0156478,
    "resourceUsage": {...},
    "inputDatasetStatistics": {...},
    "datasetStatistics": [{...}]
  }
}

Inclure la visualisation

Pour obtenir des données de visualisation pour les requêtes de journaux à l’aide de l’opérateur de rendu :

  1. Définissez la propriété include_visualization sur True.
  2. Accédez au visualization champ à l’intérieur de l’objet LogsQueryResult .

Exemple :

query = (
    "StormEvents"
    "| summarize event_count = count() by State"
    "| where event_count > 10"
    "| project State, event_count"
    "| render columnchart"
)
result = client.query_workspace(
    <workspace_id>,
    query,
    timespan=timedelta(days=1),
    include_visualization=True
    )

print(f"Visualization result: {result.visualization}")

Le visualization champ correspond à la réponse JSON brute et sa structure peut varier d’une requête à l’autre dict . Exemple :

{
  "visualization": "columnchart",
  "title": "the chart title",
  "accumulate": False,
  "isQuerySorted": False,
  "kind": None,
  "legend": None,
  "series": None,
  "yMin": "NaN",
  "yMax": "NaN",
  "xAxis": None,
  "xColumn": None,
  "xTitle": "x axis title",
  "yAxis": None,
  "yColumns": None,
  "ySplit": None,
  "yTitle": None,
  "anomalyColumns": None
}

Requête de métriques

L’exemple suivant obtient des métriques pour un abonnement Event Grid. L’URI de ressource est celui d’une rubrique Event Grid.

L’URI de ressource doit être celui de la ressource pour laquelle les métriques sont interrogées. Il est normalement au format /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Pour rechercher l’URI de ressource :

  1. Accédez à la page de votre ressource dans le Portail Azure.
  2. Dans le panneau Vue d’ensemble , sélectionnez le lien Affichage JSON .
  3. Dans le json résultant, copiez la valeur de la id propriété .

REMARQUE : Les métriques sont retournées dans l’ordre des metric_names envoyées.

import os
from datetime import timedelta, datetime
from azure.monitor.query import MetricsQueryClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = MetricsQueryClient(credential)
start_time = datetime(2021, 5, 25)
duration = timedelta(days=1)
metrics_uri = os.environ['METRICS_RESOURCE_URI']
response = client.query_resource(
    metrics_uri,
    metric_names=["PublishSuccessCount"],
    timespan=(start_time, duration)
    )

for metric in response.metrics:
    print(metric.name)
    for time_series_element in metric.timeseries:
        for metric_value in time_series_element.data:
            print(metric_value.time_stamp)

Gérer la réponse de requête des métriques

L’API de requête de métriques retourne un MetricsQueryResult objet. L’objet MetricsQueryResult contient des propriétés telles qu’une liste d’objets Metric-typed, granularity, namespaceet timespan. La Metric liste d’objets est accessible à l’aide du metrics param. Chaque Metric objet de cette liste contient une liste d’objets TimeSeriesElement . Chaque TimeSeriesElement objet contient des data propriétés et metadata_values . Sous forme visuelle, la hiérarchie d’objets de la réponse ressemble à la structure suivante :

MetricsQueryResult
|---granularity
|---timespan
|---cost
|---namespace
|---resource_region
|---metrics (list of `Metric` objects)
    |---id
    |---type
    |---name
    |---unit
    |---timeseries (list of `TimeSeriesElement` objects)
        |---metadata_values
        |---data (list of data points represented by `MetricValue` objects)

Exemple de gestion de la réponse

import os
from azure.monitor.query import MetricsQueryClient, MetricAggregationType
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = MetricsQueryClient(credential)

metrics_uri = os.environ['METRICS_RESOURCE_URI']
response = client.query_resource(
    metrics_uri,
    metric_names=["MatchedEventCount"],
    aggregations=[MetricAggregationType.COUNT]
    )

for metric in response.metrics:
    print(metric.name)
    for time_series_element in metric.timeseries:
        for metric_value in time_series_element.data:
            if metric_value.count != 0:
                print(
                    "There are {} matched events at {}".format(
                        metric_value.count,
                        metric_value.time_stamp
                    )
                )

Dépannage

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

É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 de requête Azure Monitor.

Exemples de requêtes de journaux

Exemples de requêtes de métriques

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 les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.