Delen via

Azure Monitor Query-clientbibliotheek voor Python - versie 1.2.0

  • Artikel

De Azure Monitor Query-clientbibliotheek wordt gebruikt om alleen-lezenquery's uit te voeren op de twee gegevensplatforms van Azure Monitor:

  • Logboeken : verzamelt en organiseert logboek- en prestatiegegevens van bewaakte resources. Gegevens uit verschillende bronnen, zoals platformlogboeken van Azure-services, logboek- en prestatiegegevens van agents van virtuele machines en gebruiks- en prestatiegegevens van apps, kunnen worden samengevoegd in één Azure Log Analytics-werkruimte. De verschillende gegevenstypen kunnen samen worden geanalyseerd met behulp van de Kusto-querytaal.
  • Metrische gegevens : verzamelt numerieke gegevens van bewaakte resources in een tijdreeksdatabase. Metrische gegevens zijn numerieke waarden die regelmatig worden verzameld en een bepaald aspect van een systeem op een bepaald moment beschrijven. Metrische gegevens zijn licht van gewicht en kunnen bijna realtime-scenario's ondersteunen, waardoor ze handig zijn voor waarschuwingen en snelle detectie van problemen.

Bronnen:

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Monitor Query-clientbibliotheek voor Python met pip:

pip install azure-monitor-query

De client maken

Een geverifieerde client is vereist om een query uit te voeren op logboeken of metrische gegevens. De bibliotheek bevat zowel synchrone als asynchrone vormen van de clients. Voor verificatie maakt u een exemplaar van een tokenreferentie. Gebruik dat exemplaar bij het maken van een LogsQueryClient of MetricsQueryClient. In de volgende voorbeelden wordt gebruikgemaakt DefaultAzureCredential van het pakket azure-identity .

Synchrone clients

Bekijk het volgende voorbeeld, waarin synchrone clients worden gemaakt voor het uitvoeren van query's op logboeken en metrische gegevens:

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

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

Asynchrone clients

De asynchrone vormen van de client-API's voor query's zijn te vinden in de .aio-achtervoegselnaamruimte. Bijvoorbeeld:

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)

Clients configureren voor niet-openbare Azure-clouds

En MetricsQueryClient zijn standaard LogsQueryClient geconfigureerd om verbinding te maken met de openbare Azure-cloud. Deze kunnen worden geconfigureerd om verbinding te maken met niet-openbare Azure-clouds door het juiste endpoint argument door te geven: Bijvoorbeeld:

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

Opmerking: momenteel MetricsQueryClient wordt het ARM-eindpunt (Azure Resource Manager) gebruikt voor het uitvoeren van query's op metrische gegevens, dus u hebt het bijbehorende beheereindpunt voor uw cloud nodig wanneer u deze client gebruikt. Dit kan in de toekomst veranderen.

De query uitvoeren

Zie de sectie Voorbeelden voor voorbeelden van logboeken en metrische query's.

Belangrijkste concepten

Limieten en beperkingen voor logboekquery's

De Log Analytics-service past beperking toe wanneer de aanvraagsnelheid te hoog is. Limieten, zoals het maximum aantal geretourneerde rijen, worden ook toegepast op de Kusto-query's. Zie Query-API voor meer informatie.

Als u een query voor batchlogboeken uitvoert, retourneert een beperkte aanvraag een LogsQueryError -object. De waarde van code dat object is ThrottledError.

Gegevensstructuur voor metrische gegevens

Elke set met metrische waarden is een tijdreeks met de volgende kenmerken:

  • Het tijdstip waarop de waarde is verzameld
  • De resource die is gekoppeld aan de waarde
  • Een naamruimte die fungeert als een categorie voor de metrische waarde
  • Een metrische naam
  • De waarde zelf
  • Sommige metrische gegevens kunnen meerdere dimensies hebben, zoals beschreven in multidimensionale metrische gegevens. Aangepaste metrische gegevens kunnen maximaal 10 dimensies hebben.

Voorbeelden

Query voor logboeken

In dit voorbeeld ziet u hoe u een query uitvoert op een Log Analytics-werkruimte. De pandas-bibliotheek wordt gebruikt om het antwoord te verwerken en in een tabelvorm weer te geven. Bekijk de voorbeelden als u ervoor kiest om pandas niet te gebruiken.

Tijdsperiode opgeven

De timespan parameter geeft de tijdsduur op waarvoor een query op de gegevens moet worden uitgevoerd. Deze waarde kan een van de volgende zijn:

  • een timedelta
  • een timedelta en een begindatum/tijd
  • een begindatum/einddatum

Bijvoorbeeld:

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)

Queryantwoord voor logboeken verwerken

De query_workspace API retourneert een LogsQueryResult of een LogsQueryPartialResult -object. De batch_query API retourneert een lijst die , LogsQueryPartialResulten-objecten LogsQueryError kan bevattenLogsQueryResult. Hier volgt een hiërarchie van het antwoord:

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

De LogsQueryResult itereert voor het gemak over de tabel. Als u bijvoorbeeld een queryantwoord voor logboeken wilt afhandelen met tabellen en deze wilt weergeven met pandas:

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

Een volledig voorbeeld vindt u hier.

Op een vergelijkbare manier, voor het verwerken van een queryantwoord in batchlogboeken:

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

Een volledig voorbeeld vindt u hier.

Query voor Batch-logboeken

In het volgende voorbeeld ziet u hoe u meerdere query's tegelijk verzendt met behulp van de batchquery-API. De query's kunnen worden weergegeven als een lijst LogsBatchQuery met objecten of als een woordenlijst. In dit voorbeeld wordt de vorige benadering gebruikt.

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 voor resourcelogboeken

In het volgende voorbeeld ziet u hoe u logboeken rechtstreeks vanuit een Azure-resource opvraagt zonder een Log Analytics-werkruimte te gebruiken. Hier wordt de query_resource methode gebruikt in plaats van query_workspace, en in plaats van een werkruimte-id wordt een Azure-resource-id doorgegeven (bijvoorbeeld /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)

Geavanceerde queryscenario's voor logboeken

Time-out voor logboekquery instellen

In het volgende voorbeeld ziet u het instellen van een servertime-out in seconden. Er treedt een gatewaytime-out op als de query meer tijd kost dan de genoemde time-out. De standaardwaarde is 180 seconden en kan worden ingesteld op 10 minuten (600 seconden).

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
    )

Query's uitvoeren op meerdere werkruimten

Dezelfde logboekquery kan worden uitgevoerd in meerdere Log Analytics-werkruimten. Naast de Kusto-query zijn de volgende parameters vereist:

  • workspace_id - De eerste (primaire) werkruimte-id.
  • additional_workspaces - Een lijst met werkruimten, met uitzondering van de werkruimte die in de workspace_id parameter is opgegeven. De lijstitems van de parameter kunnen bestaan uit de volgende id-indelingen:
    • Namen van gekwalificeerde werkruimten
    • Werkruimte-id's
    • Azure-resource-id's

De volgende query wordt bijvoorbeeld uitgevoerd in drie werkruimten:

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

Een volledig voorbeeld vindt u hier.

Statistieken opnemen

Ga als volgende te werk om statistieken over de uitvoering van query's in logboeken op te halen, zoals CPU- en geheugenverbruik:

  1. Stel de include_statistics parameter in op True.
  2. Open het statistics veld in het LogsQueryResult object.

In het volgende voorbeeld wordt de uitvoeringstijd van de query afgedrukt:

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

Het statistics veld is een dict die overeenkomt met het onbewerkte JSON-antwoord en de structuur ervan kan per query verschillen. De statistieken zijn te vinden in de query eigenschap. Bijvoorbeeld:

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

Visualisatie opnemen

Visualisatiegegevens ophalen voor logboekquery's met behulp van de operator render:

  1. Stel de include_visualization eigenschap in op True.
  2. Open het visualization veld in het LogsQueryResult object.

Bijvoorbeeld:

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

Het visualization veld is een dict die overeenkomt met het onbewerkte JSON-antwoord en de structuur ervan kan per query verschillen. Bijvoorbeeld:

{
  "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 voor metrische gegevens

In het volgende voorbeeld worden metrische gegevens opgehaald voor een Event Grid-abonnement. De resource-URI is die van een Event Grid-onderwerp.

De resource-URI moet die zijn van de resource waarvoor metrische gegevens worden opgevraagd. Het is normaal gesproken van de indeling /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

De resource-URI zoeken:

  1. Navigeer naar de pagina van uw resource in de Azure Portal.
  2. Selecteer op de blade Overzicht de koppeling JSON-weergave .
  3. Kopieer in de resulterende JSON de waarde van de id eigenschap.

OPMERKING: De metrische gegevens worden geretourneerd in de volgorde van de metric_names verzonden.

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)

Antwoord op query's voor metrische gegevens verwerken

De QUERY-API voor metrische gegevens retourneert een MetricsQueryResult -object. Het MetricsQueryResult object bevat eigenschappen zoals een lijst met Metric-getypte objecten, granularity, namespaceen timespan. De Metric lijst met objecten kan worden geopend met behulp van de metrics parameter . Elk Metric object in deze lijst bevat een lijst met TimeSeriesElement objecten. Elk TimeSeriesElement object bevat data en metadata_values eigenschappen. In visuele vorm lijkt de objecthiërarchie van het antwoord op de volgende structuur:

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)

Voorbeeld van het verwerken van een antwoord

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

Problemen oplossen

Zie onze gids voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.

Volgende stappen

Zie de documentatie voor de Azure Monitor-service voor meer informatie over Azure Monitor.

Voorbeelden

De volgende codevoorbeelden tonen veelvoorkomende scenario's met de Azure Monitor Query-clientbibliotheek.

Voorbeelden van logboekquery's

Queryvoorbeelden voor metrische gegevens

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit slechts één keer te doen voor alle opslagplaatsen met behulp van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.