Azure Monitor Query-Clientbibliothek für Python – Version 1.2.0

  • Artikel

Die Azure Monitor Query-Clientbibliothek wird verwendet, um schreibgeschützte Abfragen für die beiden Datenplattformen von Azure Monitor auszuführen:

  • Protokolle : Erfasst und organisiert Protokoll- und Leistungsdaten aus überwachten Ressourcen. Daten aus verschiedenen Quellen wie Plattformprotokolle von Azure-Diensten, Protokoll- und Leistungsdaten von Agents für virtuelle Computer sowie Nutzungs- und Leistungsdaten aus Apps können in einem einzelnen Azure Log Analytics-Arbeitsbereich konsolidiert werden. Die verschiedenen Datentypen können mithilfe des Kusto-Abfragesprache zusammen analysiert werden.
  • Metriken : Erfasst numerische Daten aus überwachten Ressourcen in einer Zeitreihendatenbank. Metriken sind numerische Werte, die in regelmäßigen Abständen erfasst werden und einen Aspekt eines Systems zu einem bestimmten Zeitpunkt beschreiben. Metriken sind einfach und in der Lage, Szenarien nahezu in Echtzeit zu unterstützen, sodass sie für Warnungen und schnelle Erkennung von Problemen nützlich sind.

Ressourcen:

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Monitor Query-Clientbibliothek für Python mit pip:

pip install azure-monitor-query

Erstellen des Clients

Zum Abfragen von Protokollen oder Metriken ist ein authentifizierter Client erforderlich. Die Bibliothek umfasst sowohl synchrone als auch asynchrone Formen der Clients. Erstellen Sie zum Authentifizieren eine instance mit Tokenanmeldeinformationen. Verwenden Sie diese instance, wenn Sie einen oder MetricsQueryClienterstellenLogsQueryClient. In den folgenden Beispielen wird das Paket azure-identity verwendetDefaultAzureCredential.

Synchrone Clients

Betrachten Sie das folgende Beispiel, das synchrone Clients sowohl für Protokolle als auch Metrikabfragen erstellt:

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

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

Asynchrone Clients

Die asynchronen Formen der Abfrageclient-APIs befinden sich im Namespace - .aiosuffixed. Beispiel:

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)

Konfigurieren von Clients für nicht öffentliche Azure-Clouds

Standardmäßig sind und MetricsQueryClient so konfiguriert, LogsQueryClient dass eine Verbindung mit der öffentlichen Azure-Cloud hergestellt wird. Diese können so konfiguriert werden, dass eine Verbindung mit nicht öffentlichen Azure-Clouds hergestellt wird, indem das richtige endpoint Argument übergeben wird: Beispiel:

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

Hinweis: Derzeit MetricsQueryClient wird der Azure Resource Manager -Endpunkt (ARM) zum Abfragen von Metriken verwendet, sodass Sie bei Verwendung dieses Clients den entsprechenden Verwaltungsendpunkt für Ihre Cloud benötigen. Dies kann sich in Zukunft ändern.

Führen Sie die Abfrage aus.

Beispiele für Protokolle und Metrikabfragen finden Sie im Abschnitt Beispiele .

Wichtige Begriffe

Protokollabfrageratenlimits und Drosselung

Der Log Analytics-Dienst wendet eine Drosselung an, wenn die Anforderungsrate zu hoch ist. Grenzwerte, z. B. die maximale Anzahl zurückgegebener Zeilen, werden auch auf die Kusto-Abfragen angewendet. Weitere Informationen finden Sie unter Abfrage-API.

Wenn Sie eine Batchprotokollabfrage ausführen, gibt eine gedrosselte Anforderung ein LogsQueryError Objekt zurück. Der Wert dieses code Objekts ist ThrottledError.

Metrikdatenstruktur

Jeder Satz von Metrikwerten ist eine Zeitreihe mit den folgenden Merkmalen:

  • Zeitpunkt, zu dem der Wert erfasst wurde
  • Die dem Wert zugeordnete Ressource
  • Namespace, der wie eine Kategorie für die Metrik fungiert
  • Metrikname
  • Eigentlicher Wert
  • Einige Metriken können mehrere Dimensionen aufweisen, wie in mehrdimensionalen Metriken beschrieben. Benutzerdefinierte Metriken können über bis zu 10 Dimensionen verfügen.

Beispiele

Protokollabfrage

In diesem Beispiel wird gezeigt, wie Sie einen Log Analytics-Arbeitsbereich abfragen. Um die Antwort zu behandeln und in tabellarischer Form anzuzeigen, wird die Pandas-Bibliothek verwendet. Sehen Sie sich die Beispiele an, wenn Sie pandas nicht verwenden möchten.

Angeben des Zeitraums

Der timespan Parameter gibt die Zeitdauer an, für die die Daten abfragt werden sollen. Die folgenden Werte sind möglich:

  • a timedelta
  • a timedelta und ein Startdatumtime
  • start datetime/end datetime

Beispiel:

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)

Behandeln von Protokollabfrageantworten

Die query_workspace API gibt entweder ein LogsQueryResult - oder ein LogsQueryPartialResult -Objekt zurück. Die batch_query API gibt eine Liste zurück, die , LogsQueryPartialResult- und LogsQueryError -Objekte enthalten LogsQueryResultkann. Hier sehen Sie eine Hierarchie der Antwort:

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

Der LogsQueryResult durchläuft den Tisch direkt als Komfort. Um beispielsweise eine Protokollabfrageantwort mit Tabellen zu behandeln und sie mithilfe von Pandas anzuzeigen:

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

Ein vollständiges Beispiel finden Sie hier.

In ähnlicher Weise, um eine Batchprotokollabfrageantwort zu behandeln:

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

Ein vollständiges Beispiel finden Sie hier.

Batchprotokollabfrage

Das folgende Beispiel veranschaulicht das Gleichzeitige Senden mehrerer Abfragen mithilfe der Batchabfrage-API. Die Abfragen können entweder als Liste von LogsBatchQuery Objekten oder als Wörterbuch dargestellt werden. In diesem Beispiel wird der frühere Ansatz verwendet.

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)

Ressourcenprotokollabfrage

Im folgenden Beispiel wird veranschaulicht, wie Protokolle ohne Verwendung eines Log Analytics-Arbeitsbereichs direkt aus einer Azure-Ressource abfragen. Hier wird die query_resource -Methode anstelle von query_workspaceverwendet, und anstelle einer Arbeitsbereichs-ID wird ein Azure-Ressourcenbezeichner übergeben (z. B. /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)

Szenarien für erweiterte Protokollabfragen

Festlegen des Abfragetimeouts für Protokolle

Das folgende Beispiel zeigt das Festlegen eines Servertimeouts in Sekunden. Ein Gatewaytimeout wird ausgelöst, wenn die Abfrage mehr Zeit in Anspruch nimmt als das erwähnte Timeout. Der Standardwert ist 180 Sekunden und kann bis zu 10 Minuten (600 Sekunden) eingerichtet werden.

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
    )

Abfragen mehrerer Arbeitsbereiche

Dieselbe Protokollabfrage kann in mehreren Log Analytics-Arbeitsbereichen ausgeführt werden. Zusätzlich zur Kusto-Abfrage sind die folgenden Parameter erforderlich:

  • workspace_id – Die erste (primäre) Arbeitsbereichs-ID.
  • additional_workspaces – Eine Liste von Arbeitsbereichen mit Ausnahme des im workspace_id -Parameter angegebenen Arbeitsbereichs. Die Listenelemente des Parameters können aus den folgenden Bezeichnerformaten bestehen:
    • Qualifizierte Arbeitsbereichsnamen
    • Arbeitsbereichs-IDs
    • Azure-Ressourcen-IDs

Die folgende Abfrage wird beispielsweise in drei Arbeitsbereichen ausgeführt:

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

Ein vollständiges Beispiel finden Sie hier.

Einschließen von Statistiken

So rufen Sie Protokollabfrageausführungsstatistiken ab, z. B. CPU- und Arbeitsspeicherverbrauch:

  1. Setzen Sie den include_statistics-Parameter auf True.
  2. Greifen Sie auf das statistics Feld innerhalb des LogsQueryResult -Objekts zu.

Im folgenden Beispiel wird die Abfrageausführungszeit ausgegeben:

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

Das statistics Feld ist ein dict , das der unformatierten JSON-Antwort entspricht, und seine Struktur kann je nach Abfrage variieren. Die Statistiken befinden sich in der query -Eigenschaft. Beispiel:

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

Einschließen der Visualisierung

So rufen Sie Visualisierungsdaten für Protokollabfragen mithilfe des Renderoperators ab:

  1. Setzen Sie die include_visualization-Eigenschaft auf True.
  2. Greifen Sie auf das visualization Feld innerhalb des LogsQueryResult -Objekts zu.

Beispiel:

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

Das visualization Feld ist ein dict , das der unformatierten JSON-Antwort entspricht, und seine Struktur kann je nach Abfrage variieren. Beispiel:

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

Metrikabfrage

Im folgenden Beispiel werden Metriken für ein Event Grid-Abonnement abgerufen. Der Ressourcen-URI ist der eines Event Grid-Themas.

Der Ressourcen-URI muss dem der Ressource entsprechen, für die Metriken abgefragt werden. Sie hat normalerweise das Format /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

So suchen Sie den Ressourcen-URI:

  1. Navigieren Sie im Azure-Portal zur Seite Ihrer Ressource.
  2. Wählen Sie auf dem Blatt Übersicht den Link JSON-Ansicht aus.
  3. Kopieren Sie im resultierenden JSON-Code den Wert der id Eigenschaft.

HINWEIS: Die Metriken werden in der Reihenfolge der gesendeten metric_names zurückgegeben.

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)

Verarbeiten der Antwort auf Metrikabfragen

Die Metrikabfrage-API gibt ein MetricsQueryResult -Objekt zurück. Das MetricsQueryResult -Objekt enthält Eigenschaften wie eine Liste von Metric-typisierten Objekten, granularity, namespaceund timespan. Auf die Metric Objektliste kann mithilfe des metrics Param zugegriffen werden. Jedes Metric Objekt in dieser Liste enthält eine Liste von TimeSeriesElement Objekten. Jedes TimeSeriesElement Objekt enthält data - und metadata_values -Eigenschaften. In visueller Form ähnelt die Objekthierarchie der Antwort der folgenden 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)

Beispiel für die Behandlung einer Antwort

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

Problembehandlung

Weitere Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung .

Nächste Schritte

Weitere Informationen zu Azure Monitor finden Sie in der Dokumentation zum Azure Monitor-Dienst.

Beispiele

Die folgenden Codebeispiele zeigen allgemeine Szenarien mit der Azure Monitor Query-Clientbibliothek.

Beispiele für Protokollabfragen

Beispiele für Metrikabfragen

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys mit unserer CLA tun.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.