Azure Monitor Query-Clientbibliothek für Python – Version 1.2.0
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:
- Quellcode
- Paket (PyPI)
- Paket (Conda)
- API-Referenzdokumentation
- Dienstdokumentation
- Beispiele
- Änderungsprotokoll
Erste Schritte
Voraussetzungen
- Python 3.7 oder höher
- Ein Azure-Abonnement
- Eine TokenCredential-Implementierung, z. B. ein Anmeldeinformationstyp der Azure Identity-Bibliothek.
- Zum Abfragen von Protokollen benötigen Sie einen Azure Log Analytics-Arbeitsbereich.
- Zum Abfragen von Metriken benötigen Sie eine Azure-Ressource jeglicher Art (Speicherkonto, Key Vault, Cosmos DB usw.).
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 MetricsQueryClient
erstellenLogsQueryClient
. 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 - .aio
suffixed. 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
- Batchprotokollabfrage
- Ressourcenprotokollabfrage
- Szenarien mit erweiterten Protokollabfragen
- Metrikabfrage
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 LogsQueryResult
kann. 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_workspace
verwendet, 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 imworkspace_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:
- Setzen Sie den
include_statistics
-Parameter aufTrue
. - Greifen Sie auf das
statistics
Feld innerhalb desLogsQueryResult
-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:
- Setzen Sie die
include_visualization
-Eigenschaft aufTrue
. - Greifen Sie auf das
visualization
Feld innerhalb desLogsQueryResult
-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:
- Navigieren Sie im Azure-Portal zur Seite Ihrer Ressource.
- Wählen Sie auf dem Blatt Übersicht den Link JSON-Ansicht aus.
- 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
, namespace
und 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
- Senden einer einzelnen Abfrage mit LogsQueryClient und Behandeln der Antwort als Tabelle (asynchrones Beispiel)
- Senden einer einzelnen Abfrage mit LogsQueryClient und Behandeln der Antwort in Schlüssel-Wert-Form
- Senden einer einzelnen Abfrage mit LogsQueryClient ohne Pandas
- Senden einer einzelnen Abfrage mit LogsQueryClient über mehrere Arbeitsbereiche hinweg
- Senden mehrerer Abfragen mit LogsQueryClient
- Senden einer einzelnen Abfrage mit LogsQueryClient mithilfe des Servertimeouts
Beispiele für Metrikabfragen
- Senden einer Abfrage mithilfe von MetricsQueryClient (asynchrones Beispiel)
- Abrufen einer Liste von Metriknamespaces (asynchrones Beispiel)
- Abrufen einer Liste von Metrikdefinitionen (asynchrones Beispiel)
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.
Azure SDK for Python