Biblioteka klienta zapytań usługi Azure Monitor dla języka Python — wersja 1.2.0

  • Artykuł

Biblioteka klienta zapytań usługi Azure Monitor służy do wykonywania zapytań tylko do odczytu na dwóch platformach danych usługi Azure Monitor:

  • Dzienniki — zbiera i organizuje dane dzienników i wydajności z monitorowanych zasobów. Dane z różnych źródeł, takich jak dzienniki platformy z usług platformy Azure, dane dzienników i wydajności agentów maszyn wirtualnych, a dane użycia i wydajności z aplikacji można skonsolidować w jednym obszarze roboczym usługi Azure Log Analytics. Różne typy danych można analizować razem przy użyciu język zapytań Kusto.
  • Metryki — zbiera dane liczbowe z monitorowanych zasobów do bazy danych szeregów czasowych. Metryki to wartości liczbowe, które są zbierane w regularnych odstępach czasu i opisują jakiś aspekt systemu w określonym czasie. Metryki są lekkie i mogą obsługiwać scenariusze niemal w czasie rzeczywistym, co ułatwia alerty i szybkie wykrywanie problemów.

Zasoby:

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta zapytań usługi Azure Monitor dla języka Python za pomocą narzędzia pip:

pip install azure-monitor-query

Tworzenie klienta

Uwierzytelniony klient jest wymagany do wykonywania zapytań dotyczących dzienników lub metryk. Biblioteka zawiera zarówno synchroniczne, jak i asynchroniczne formy klientów. Aby przeprowadzić uwierzytelnianie, utwórz wystąpienie poświadczeń tokenu. Użyj tego wystąpienia podczas tworzenia obiektu LogsQueryClient lub MetricsQueryClient. W poniższych przykładach użyto pakietu DefaultAzureCredentialazure-identity .

Klienci synchronicznie

Rozważmy następujący przykład, który tworzy klientów synchronicznych dla zapytań dotyczących dzienników i metryk:

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

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

Klienci asynchroniczne

Asynchroniczne formularze interfejsów API klienta zapytań znajdują się w przestrzeni nazw z sufiksem - sufiksem .aio. Na przykład:

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)

Konfigurowanie klientów dla chmur platformy Azure innych niż publiczne

Domyślnie LogsQueryClient i MetricsQueryClient są skonfigurowane do nawiązywania połączenia z publiczną chmurą platformy Azure. Można je skonfigurować do łączenia się z chmurami platformy Azure spoza publicznej chmury platformy Azure, przekazując poprawny endpoint argument: Na przykład:

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

Uwaga: obecnie MetricsQueryClient używa punktu końcowego usługi Azure Resource Manager (ARM) do wykonywania zapytań dotyczących metryk, dlatego podczas korzystania z tego klienta będzie potrzebny odpowiedni punkt końcowy zarządzania dla chmury. Może to ulec zmianie w przyszłości.

Wykonaj zapytanie

Przykłady zapytań dzienników i metryk można znaleźć w sekcji Przykłady .

Kluczowe pojęcia

Rejestruje limity szybkości zapytań i ograniczanie przepustowości

Usługa Log Analytics stosuje ograniczanie przepustowości, gdy szybkość żądania jest zbyt wysoka. Limity, takie jak maksymalna liczba zwracanych wierszy, są również stosowane do zapytań Kusto. Aby uzyskać więcej informacji, zobacz Interfejs API zapytań.

Jeśli wykonujesz zapytanie dotyczące dzienników wsadowych, żądanie ograniczone zwróci LogsQueryError obiekt. Wartość tego obiektu code będzie wynosić ThrottledError.

Struktura danych metryk

Każdy zestaw wartości metryk jest szeregiem czasowym o następujących cechach:

  • Czas zbierania wartości
  • Zasób skojarzony z wartością
  • Przestrzeń nazw, która działa jak kategoria metryki
  • Nazwa metryki
  • Sama wartość
  • Niektóre metryki mogą mieć wiele wymiarów zgodnie z opisem w metrykach wielowymiarowych. Metryki niestandardowe mogą mieć maksymalnie 10 wymiarów.

Przykłady

Zapytanie dotyczące dzienników

W tym przykładzie pokazano, jak wykonywać zapytania dotyczące obszaru roboczego usługi Log Analytics. Aby obsłużyć odpowiedź i wyświetlić ją w formie tabelarycznej, używana jest biblioteka pandas . Zobacz przykłady , jeśli nie chcesz używać biblioteki pandas.

Określ przedział czasu

Parametr timespan określa czas trwania zapytania o dane. Ta wartość może być jedną z następujących wartości:

  • A timedelta
  • a timedelta i data/godzina rozpoczęcia
  • data/godzina rozpoczęcia/data/godzina zakończenia

Na przykład:

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)

Obsługa odpowiedzi zapytania dotyczącego dzienników

Interfejs query_workspace API zwraca LogsQueryResult obiekt lub LogsQueryPartialResult . Interfejs batch_query API zwraca listę, która może zawierać LogsQueryResultobiekty , LogsQueryPartialResulti LogsQueryError . Oto hierarchia odpowiedzi:

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

Bezpośrednio LogsQueryResult iteruje po tabeli jako wygodę. Aby na przykład obsłużyć odpowiedź na zapytanie dzienników z tabelami i wyświetlić ją przy użyciu biblioteki pandas:

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

Pełny przykład można znaleźć tutaj.

W podobny sposób do obsługi odpowiedzi zapytania dzienników wsadowych:

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

Pełny przykład można znaleźć tutaj.

Zapytanie dotyczące dzienników usługi Batch

W poniższym przykładzie pokazano wysyłanie wielu zapytań jednocześnie przy użyciu interfejsu API zapytań wsadowych. Zapytania mogą być reprezentowane jako lista LogsBatchQuery obiektów lub słownika. W tym przykładzie użyto poprzedniego podejścia.

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)

Zapytanie dotyczące dzienników zasobów

W poniższym przykładzie pokazano, jak wykonywać zapytania dotyczące dzienników bezpośrednio z zasobu platformy Azure bez korzystania z obszaru roboczego usługi Log Analytics. query_resource W tym miejscu metoda jest używana zamiast query_workspace, a zamiast identyfikatora obszaru roboczego identyfikator zasobu platformy Azure jest przekazywany (np. /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)

Zaawansowane scenariusze zapytań dzienników

Ustawianie limitu czasu zapytania dzienników

W poniższym przykładzie pokazano ustawienie limitu czasu serwera w sekundach. Limit czasu bramy jest zgłaszany, jeśli zapytanie zajmuje więcej czasu niż wspomniany limit czasu. Wartość domyślna to 180 sekund i można skonfigurować do 10 minut (600 sekund).

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
    )

Wykonywanie zapytań dotyczących wielu obszarów roboczych

To samo zapytanie dzienników można wykonać w wielu obszarach roboczych usługi Log Analytics. Oprócz zapytania Kusto wymagane są następujące parametry:

  • workspace_id — pierwszy (podstawowy) identyfikator obszaru roboczego.
  • additional_workspaces — Lista obszarów roboczych z wyłączeniem obszaru roboczego podanego w parametrze workspace_id . Elementy listy parametru mogą składać się z następujących formatów identyfikatorów:
    • Kwalifikowane nazwy obszarów roboczych
    • Identyfikatory obszarów roboczych
    • Identyfikatory zasobów platformy Azure

Na przykład następujące zapytanie jest wykonywane w trzech obszarach roboczych:

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

Pełny przykład można znaleźć tutaj.

Uwzględnij statystyki

Aby uzyskać statystyki wykonywania zapytań dzienników, takie jak użycie procesora CPU i pamięci:

  1. include_statistics Ustaw parametr na Truewartość .
  2. statistics Uzyskaj dostęp do pola wewnątrz LogsQueryResult obiektu.

Poniższy przykład wyświetla czas wykonywania zapytania:

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

Pole statistics to dict , które odpowiada nieprzetworzonej odpowiedzi JSON, a jego struktura może różnić się w zależności od zapytania. Statystyki znajdują się we query właściwości . Na przykład:

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

Dołączanie wizualizacji

Aby uzyskać dane wizualizacji dla zapytań dotyczących dzienników przy użyciu operatora renderowania:

  1. include_visualization Ustaw właściwość na Truewartość .
  2. visualization Uzyskaj dostęp do pola wewnątrz LogsQueryResult obiektu.

Na przykład:

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

Pole visualization to dict , które odpowiada nieprzetworzonej odpowiedzi JSON, a jego struktura może różnić się w zależności od zapytania. Na przykład:

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

Zapytanie metryk

Poniższy przykład pobiera metryki dla subskrypcji usługi Event Grid. Identyfikator URI zasobu jest identyfikatorem URI tematu usługi Event Grid.

Identyfikator URI zasobu musi być identyfikatorem URI zasobu, dla którego są wykonywane zapytania dotyczące metryk. Zwykle jest to format /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Aby znaleźć identyfikator URI zasobu:

  1. Przejdź do strony zasobu w Azure Portal.
  2. W bloku Przegląd wybierz link Widok JSON .
  3. W wynikowym formacie JSON skopiuj wartość id właściwości .

UWAGA: Metryki są zwracane w kolejności wysyłania metric_names.

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)

Obsługa odpowiedzi na zapytanie metryk

Interfejs API zapytań metryk zwraca MetricsQueryResult obiekt. Obiekt MetricsQueryResult zawiera właściwości, takie jak lista Metricobiektów typizowane, granularity, namespacei timespan. Dostęp Metric do listy obiektów można uzyskać za pomocą parametru metrics . Każdy Metric obiekt na tej liście zawiera listę TimeSeriesElement obiektów. Każdy TimeSeriesElement obiekt zawiera data właściwości i metadata_values . W formie wizualizacji hierarchia obiektów odpowiedzi przypomina następującą 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)

Przykład obsługi odpowiedzi

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

Rozwiązywanie problemów

Zobacz nasz przewodnik rozwiązywania problemów , aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii.

Następne kroki

Aby dowiedzieć się więcej na temat usługi Azure Monitor, zobacz dokumentację usługi Azure Monitor.

Przykłady

Poniższe przykłady kodu pokazują typowe scenariusze z biblioteką klienta zapytań usługi Azure Monitor.

Przykłady zapytań dotyczących dzienników

Przykłady zapytań metryk

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Należy to zrobić tylko raz we wszystkich repozytoriach przy użyciu naszego cla.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.