Azure Monitor Query-klientbibliotek för Python – version 1.2.0

Azure Monitor Query-klientbiblioteket används för att köra skrivskyddade frågor mot Azure Monitors två dataplattformar:

• Loggar – Samlar in och organiserar logg- och prestandadata från övervakade resurser. Data från olika källor, till exempel plattformsloggar från Azure-tjänster, logg- och prestandadata från agenter för virtuella datorer, och användnings- och prestandadata från appar kan konsolideras till en enda Azure Log Analytics-arbetsyta. De olika datatyperna kan analyseras tillsammans med hjälp av Kusto-frågespråk.
• Mått – Samlar in numeriska data från övervakade resurser till en tidsseriedatabas. Mått är numeriska värden som samlas in med jämna mellanrum och beskriver någon aspekt av ett system vid en viss tidpunkt. Mått är enkla och kan stödja scenarier i nära realtid, vilket gör dem användbara för aviseringar och snabb identifiering av problem.

Resurser:

• Källkod
• Paket (PyPI)
• Paket (Conda)
• Referensdokumentation för API
• Tjänstdokumentation
• Exempel
• Ändringslogg

Komma igång

Förutsättningar

• Python 3.7 eller senare
• En Azure-prenumeration
• En TokenCredential-implementering , till exempel en autentiseringstyp för Azure Identity-bibliotek.
• För att köra frågor mot loggar behöver du en Azure Log Analytics-arbetsyta.
• För att köra frågor mot mått behöver du en Azure-resurs av något slag (lagringskonto, Key Vault, Cosmos DB osv.).

Installera paketet

Installera Azure Monitor Query-klientbiblioteket för Python med pip:

pip install azure-monitor-query

Skapa klienten

En autentiserad klient krävs för att köra frågor mot loggar eller mått. Biblioteket innehåller både synkrona och asynkrona former av klienterna. Om du vill autentisera skapar du en instans av en tokenautentiseringsuppgift. Använd den instansen när du skapar en LogsQueryClient eller MetricsQueryClient. Följande exempel använder DefaultAzureCredential från azure-identity-paketet .

Synkrona klienter

Tänk dig följande exempel, som skapar synkrona klienter för frågor om både loggar och mått:

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

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

Asynkrona klienter

De asynkrona formerna för frågeklient-API:erna finns i .aionamnområdet -suffix. Ett exempel:

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)

Konfigurera klienter för icke-offentliga Azure-moln

Som standard LogsQueryClient och MetricsQueryClient konfigureras för att ansluta till det offentliga Azure-molnet. Dessa kan konfigureras för att ansluta till icke-offentliga Azure-moln genom att skicka in rätt endpoint argument: Till exempel:

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

Obs! För närvarande MetricsQueryClient använder azure Resource Manager-slutpunkten (ARM) för att köra frågor mot mått, så du behöver motsvarande hanteringsslutpunkt för molnet när du använder den här klienten. Detta kan komma att ändras i framtiden.

Kör frågan

Exempel på loggar och måttfrågor finns i avsnittet Exempel .

Viktiga begrepp

Loggar frågefrekvensgränser och begränsning

Log Analytics-tjänsten tillämpar begränsningar när begärandefrekvensen är för hög. Gränser, till exempel det maximala antalet rader som returneras, tillämpas också på Kusto-frågorna. Mer information finns i Fråge-API.

Om du kör en batchloggfråga returnerar en begränsad begäran ett LogsQueryError objekt. Objektets code värde blir ThrottledError.

Datastruktur för mått

Varje uppsättning måttvärden är en tidsserie med följande egenskaper:

• Den tid då värdet samlades in
• Resursen som är associerad med värdet
• Ett namnområde som fungerar som en kategori för måttet
• Ett måttnamn
• Själva värdet
• Vissa mått kan ha flera dimensioner enligt beskrivningen i flerdimensionella mått. Anpassade mått kan ha upp till 10 dimensioner.

Exempel

• Loggfråga
  • Ange tidsintervall
  • Hantera svar på loggfrågor
• Fråga om Batch-loggar
• Fråga om resursloggar
• Frågescenarier för avancerade loggar
  • Ange tidsgräns för frågor i loggar
  • Fråga flera arbetsytor
  • Ta med statistik
  • Inkludera visualisering
• Måttfråga
  • Hantera svar på måttfrågor
  • Exempel på hantering av svar

Loggfråga

Det här exemplet visar hur du kör frågor mot en Log Analytics-arbetsyta. Pandas-biblioteket används för att hantera svaret och visa det i tabellformat. Se exemplen om du väljer att inte använda Pandas.

Ange tidsintervall

Parametern timespan anger hur lång tid det tar att fråga efter data. Det här värdet kan vara något av följande:

• A timedelta
• a timedelta och en startdatumtid
• en start datetime/end datetime

Ett exempel:

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)

Hantera svar på loggfrågor

API:et query_workspace returnerar antingen ett LogsQueryResult eller ett LogsQueryPartialResult objekt. API:et batch_query returnerar en lista som kan innehålla LogsQueryResult, LogsQueryPartialResultoch LogsQueryError objekt. Här är en hierarki med svaret:

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

Direkt LogsQueryResult itererar över tabellen som en bekvämlighet. Om du till exempel vill hantera ett loggfrågesvar med tabeller och visa det med hjälp av Pandas:

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

Ett fullständigt exempel finns här.

På liknande sätt kan du hantera ett frågesvar för batchloggar:

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

Ett fullständigt exempel finns här.

Fråga om Batch-loggar

I följande exempel visas hur du skickar flera frågor samtidigt med hjälp av batch-fråge-API:et. Frågorna kan antingen representeras som en lista över LogsBatchQuery objekt eller en ordlista. I det här exemplet används den tidigare metoden.

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)

Fråga om resursloggar

I följande exempel visas hur du frågar efter loggar direkt från en Azure-resurs utan att använda en Log Analytics-arbetsyta. query_resource Här används metoden i stället för query_workspace, och i stället för ett arbetsyte-ID skickas en Azure-resursidentifierare in (t.ex. /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)

Frågescenarier för avancerade loggar

Ange tidsgräns för frågor i loggar

I följande exempel visas hur du anger en tidsgräns för servern i sekunder. En gateway-timeout aktiveras om frågan tar längre tid än den angivna tidsgränsen. Standardvärdet är 180 sekunder och kan ställas in på 10 minuter (600 sekunder).

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
    )

Fråga flera arbetsytor

Samma loggfråga kan köras på flera Log Analytics-arbetsytor. Förutom Kusto-frågan krävs följande parametrar:

• workspace_id – Det första (primära) arbetsyte-ID:t.
• additional_workspaces – En lista över arbetsytor, exklusive arbetsytan som anges i parametern workspace_id . Parameterns listobjekt kan bestå av följande identifierarformat:
  • Namn på kvalificerade arbetsytor
  • Arbetsyte-ID:t
  • Azure-resurs-ID:t

Följande fråga körs till exempel på tre arbetsytor:

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

Ett fullständigt exempel finns här.

Ta med statistik

Så här hämtar du körningsstatistik för loggar, till exempel PROCESSOR- och minnesförbrukning:

1. Ange parametern include_statistics till True.
2. Öppna fältet statistics inuti LogsQueryResult objektet.

I följande exempel skrivs frågekörningstiden ut:

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

Fältet statistics är ett dict som motsvarar det råa JSON-svaret och dess struktur kan variera beroende på fråga. Statistiken finns i egenskapen query . Ett exempel:

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

Inkludera visualisering

Så här hämtar du visualiseringsdata för loggfrågor med hjälp av återgivningsoperatorn:

1. Ange egenskapen include_visualization till True.
2. Öppna fältet visualization inuti LogsQueryResult objektet.

Ett exempel:

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

Fältet visualization är ett dict som motsvarar det råa JSON-svaret och dess struktur kan variera beroende på fråga. Ett exempel:

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

Måttfråga

I följande exempel hämtas mått för en Event Grid-prenumeration. Resurs-URI:n är ett Event Grid-ämne.

Resurs-URI:n måste vara den resurs för vilken mått efterfrågas. Det är normalt av formatet /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Så här hittar du resurs-URI:n:

1. Gå till resurssidan i Azure Portal.
2. På bladet Översikt väljer du länken JSON-vy .
3. I den resulterande JSON kopierar du värdet för id egenskapen.

Obs! Måtten returneras i den ordning som metric_names skickas.

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)

Hantera svar på måttfrågor

Fråge-API:et för mått returnerar ett MetricsQueryResult objekt. Objektet MetricsQueryResult innehåller egenskaper som en lista över Metric-typade objekt, granularity, namespaceoch timespan. Objektlistan Metric kan nås med hjälp av metrics param. Varje Metric objekt i den här listan innehåller en lista över TimeSeriesElement objekt. Varje TimeSeriesElement objekt innehåller data och metadata_values egenskaper. I visuellt format liknar objekthierarkin för svaret följande struktur:

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)

Exempel på hantering av svar

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

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i vår felsökningsguide .

Nästa steg

Mer information om Azure Monitor finns i dokumentationen för Azure Monitor-tjänsten.

Exempel

Följande kodexempel visar vanliga scenarier med Azure Monitor Query-klientbiblioteket.

Frågeexempel för loggar

• Skicka en enskild fråga med LogsQueryClient och hantera svaret som en tabell (asynkront exempel)
• Skicka en enskild fråga med LogsQueryClient och hantera svaret i nyckel/värde-formulär
• Skicka en enda fråga med LogsQueryClient utan Pandas
• Skicka en enda fråga med LogsQueryClient över flera arbetsytor
• Skicka flera frågor med LogsQueryClient
• Skicka en enskild fråga med LogsQueryClient med hjälp av serverns tidsgräns

Frågeexempel för mått

• Skicka en fråga med MetricsQueryClient (async-exempel)
• Hämta en lista över måttnamnområden (async-exempel)
• Hämta en lista över måttdefinitioner (asynkront exempel)

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång i alla lagringsplatser med vår CLA.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.