Libreria client di Query di Monitoraggio di Azure per Python - versione 1.2.0

  • Articolo

La libreria client di Query di Monitoraggio di Azure viene usata per eseguire query di sola lettura su due piattaforme dati di Monitoraggio di Azure:

  • Log : raccoglie e organizza i dati dei log e delle prestazioni dalle risorse monitorate. I dati provenienti da origini diverse, ad esempio i log della piattaforma, i servizi di Azure, i log e i dati sulle prestazioni degli agenti delle macchine virtuali, nonché i dati sull'utilizzo e sulle prestazioni delle app possono essere consolidati in un'unica area di lavoro di Azure Log Analytics. I vari tipi di dati possono essere analizzati insieme usando la Linguaggio di query Kusto.
  • Metriche : raccoglie i dati numerici dalle risorse monitorate in un database di serie temporali. Le metriche sono valori numerici che vengono raccolti a intervalli regolari e che descrivono un aspetto di un sistema in un determinato momento. Le metriche sono semplici e in grado di supportare scenari quasi in tempo reale, rendendoli utili per l'avviso e il rilevamento rapido dei problemi.

Risorse:

Introduzione

Prerequisiti

Installare il pacchetto

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

pip install azure-monitor-query

Creare il client

Per eseguire query sui log o sulle metriche, è 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 LogsQueryClient oggetto o MetricsQueryClient. Gli esempi seguenti usano DefaultAzureCredential il pacchetto azure-identity .

Client sincroni

Si consideri l'esempio seguente, che crea client sincroni per le query log e metriche:

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

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

Client asincroni

Le forme asincrone delle API client di query sono disponibili nello .aiospazio dei nomi -suffisso. Ad esempio:

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)

Configurare i client per cloud di Azure non pubblici

Per impostazione predefinita, LogsQueryClient e MetricsQueryClient sono configurati per connettersi al cloud di Azure pubblico. Queste possono essere configurate per connettersi ai cloud di Azure non pubblici passando l'argomento corretto endpoint : ad esempio:

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

Nota: attualmente usa MetricsQueryClient l'endpoint di Azure Resource Manager (ARM) per eseguire query sulle metriche, quindi sarà necessario l'endpoint di gestione corrispondente per il cloud quando si usa questo client. Questo è soggetto a modifiche in futuro.

Esecuzione della query

Per esempi di query log e metriche, vedere la sezione Esempi .

Concetti chiave

Log limiti di frequenza di query e limitazione

Il servizio Log Analytics applica la limitazione quando la frequenza delle richieste è troppo elevata. I limiti, ad esempio il numero massimo di righe restituiti, vengono applicati anche alle query Kusto. Per altre informazioni, vedere API query.

Se si esegue una query dei log batch, una richiesta limitata restituirà un LogsQueryError oggetto. Il valore dell'oggetto code sarà ThrottledError.

Struttura dei dati delle metriche

Ogni set di valori delle metriche è una serie temporale con le caratteristiche seguenti:

  • Ora in cui è stato raccolto il valore
  • Risorsa associata al valore
  • Spazio dei nomi che funge da categoria per la metrica
  • Nome della metrica
  • Valore stesso
  • Alcune metriche possono avere più dimensioni, come descritto nelle metriche multidimensionali. Le metriche personalizzate possono avere fino a 10 dimensioni.

Esempio

Query sui log

In questo esempio viene illustrato come eseguire query su un'area di lavoro Log Analytics. Per gestire la risposta e visualizzarla in un modulo tabulare, viene usata la libreria pandas . Vedere gli esempi se si sceglie di non usare pandas.

Specifica intervallo di tempo

Il timespan parametro specifica la durata dell'ora per cui eseguire query sui dati. I valori validi sono i seguenti:

  • a timedelta
  • a e un timedelta datetime di inizio
  • un datetime/end datetime di inizio

Ad esempio:

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)

Gestire la risposta alle query dei log

L'API query_workspace restituisce un LogsQueryResult oggetto o un LogsQueryPartialResult oggetto. L'API batch_query restituisce un elenco che può contenere LogsQueryResultoggetti , LogsQueryPartialResulte LogsQueryError . Ecco una gerarchia della risposta:

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

L'iterazione LogsQueryResult diretta della tabella viene eseguita come praticità. Ad esempio, per gestire una risposta di query dei log con tabelle e visualizzarla usando pandas:

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

Un esempio completo è disponibile qui.

In modo analogo, per gestire una risposta di query dei log batch:

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

Un esempio completo è disponibile qui.

Query sui log batch

Nell'esempio seguente viene illustrato l'invio di più query contemporaneamente tramite l'API query batch. Le query possono essere rappresentate come elenco di LogsBatchQuery oggetti o un dizionario. In questo esempio viene usato l'approccio precedente.

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)

Query sui log delle risorse

Nell'esempio seguente viene illustrato come eseguire query sui log direttamente da una risorsa di Azure senza usare un'area di lavoro Log Analytics. In questo caso, il query_resource metodo viene usato anziché , e invece di query_workspaceun ID dell'area di lavoro, viene passato un identificatore di risorsa di Azure (ad esempio /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)

Scenari di query di log avanzati

Impostare il timeout delle query dei log

Nell'esempio seguente viene illustrato l'impostazione di un timeout del server in secondi. Viene generato un timeout del gateway se la query richiede più tempo del timeout indicato. Il valore predefinito è 180 secondi e può essere configurato fino a 10 minuti (600 secondi).

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
    )

Eseguire query su più aree di lavoro

La stessa query di log può essere eseguita in più aree di lavoro di Log Analytics. Oltre alla query Kusto, sono necessari i parametri seguenti:

  • workspace_id - Il primo ID dell'area di lavoro (primaria).
  • additional_workspaces - Elenco di aree di lavoro, escluse le aree di lavoro fornite nel workspace_id parametro. Gli elementi dell'elenco dei parametri possono essere costituiti dai formati di identificatore seguenti:
    • Nomi di area di lavoro qualificati
    • ID area di lavoro
    • ID risorsa di Azure

Ad esempio, la query seguente viene eseguita in tre aree di lavoro:

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

Un esempio completo è disponibile qui.

Includere le statistiche

Per ottenere le statistiche di esecuzione delle query dei log, ad esempio l'utilizzo della CPU e della memoria:

  1. Impostare il parametro include_statistics su True.
  2. Accedere al statistics campo all'interno dell'oggetto LogsQueryResult .

Nell'esempio seguente viene stampato il tempo di esecuzione della query:

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

Il statistics campo è un dict oggetto che corrisponde alla risposta JSON non elaborata e la relativa struttura può variare in base alla query. Le statistiche vengono trovate all'interno della query proprietà. Ad esempio:

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

Includere la visualizzazione

Per ottenere i dati di visualizzazione per le query di log usando l'operatore di rendering:

  1. Impostare la proprietà include_visualization su True.
  2. Accedere al visualization campo all'interno dell'oggetto LogsQueryResult .

Ad esempio:

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

Il visualization campo è un dict oggetto che corrisponde alla risposta JSON non elaborata e la relativa struttura può variare in base alla query. Ad esempio:

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

Query sulle metriche

Nell'esempio seguente vengono recuperate le metriche per una sottoscrizione di Griglia di eventi. L'URI della risorsa è quello di un argomento griglia di eventi.

L'URI della risorsa deve essere quello della risorsa per cui vengono eseguite query sulle metriche. Normalmente è del formato /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Per trovare l'URI della risorsa:

  1. Passare alla pagina della risorsa nel portale di Azure.
  2. Nel pannello Panoramica selezionare il collegamento Visualizzazione JSON .
  3. Nel codice JSON risultante copiare il valore della id proprietà.

NOTA: le metriche vengono restituite nell'ordine del metric_names inviato.

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)

Gestire la risposta alle query sulle metriche

L'API query delle metriche restituisce un MetricsQueryResult oggetto. L'oggetto MetricsQueryResult contiene proprietà come un elenco di Metricoggetti tipizzati, , granularity, namespacee timespan. È Metric possibile accedere all'elenco di oggetti usando il metrics param. Ogni Metric oggetto in questo elenco contiene un elenco di TimeSeriesElement oggetti. Ogni TimeSeriesElement oggetto contiene data e metadata_values proprietà. In formato visivo, la gerarchia di oggetti della risposta è simile alla struttura seguente:

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)

Esempio di gestione della risposta

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

Risoluzione dei problemi

Per informazioni dettagliate su come diagnosticare 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 mostrano scenari comuni con la libreria client di Query di Monitoraggio di Azure.

Esempi di query di log

Esempi di query sulle metriche

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. Questa operazione deve essere eseguita una sola volta in tutti i repository usando l'applicazione cla.

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