Klientská knihovna azure Monitor Query pro Python – verze 1.2.0

  • Článek

Klientská knihovna dotazů služby Azure Monitor se používá ke spouštění dotazů jen pro čtení na dvou datových platformách služby Azure Monitor:

  • Protokoly – shromažďuje a uspořádá data protokolů a výkonu z monitorovaných prostředků. Data z různých zdrojů, jako jsou protokoly platformy ze služeb Azure, data protokolů a výkonu od agentů virtuálních počítačů a data o využití a výkonu z aplikací, je možné konsolidovat do jednoho pracovního prostoru služby Azure Log Analytics. Různé datové typy lze analyzovat společně pomocí dotazovací jazyk Kusto.
  • Metriky – shromažďuje číselná data z monitorovaných prostředků do databáze časových řad. Metriky jsou číselné hodnoty, které se shromažďují v pravidelných intervalech a popisují určité aspekty systému v určitém čase. Metriky jsou jednoduché a dokážou podporovat scénáře téměř v reálném čase, takže jsou užitečné pro upozorňování a rychlé zjišťování problémů.

Zdroje a prostředky:

Začínáme

Požadavky

Instalace balíčku

Nainstalujte klientskou knihovnu dotazů služby Azure Monitor pro Python pomocí příkazu pip:

pip install azure-monitor-query

Vytvoření klienta

K dotazování protokolů nebo metrik se vyžaduje ověřený klient. Knihovna obsahuje synchronní i asynchronní formy klientů. K ověření vytvořte instanci přihlašovacích údajů tokenu. Tuto instanci použijte při vytváření LogsQueryClient nebo MetricsQueryClient. Následující příklady používají DefaultAzureCredential balíček azure-identity .

Synchronní klienti

Podívejte se na následující příklad, který vytvoří synchronní klienty pro dotazování na protokoly i metriky:

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

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

Asynchronní klienti

Asynchronní formy rozhraní API klienta dotazů se nacházejí v oboru názvů s příponou .aio-. Příklad:

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)

Konfigurace klientů pro neveřejné cloudy Azure

Ve výchozím nastavení LogsQueryClient a MetricsQueryClient jsou nakonfigurované pro připojení k veřejnému cloudu Azure. Můžete je nakonfigurovat tak, aby se připojovaly k neveřejním cloudům Azure předáním správného endpoint argumentu: Například:

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

Poznámka: V současné době MetricsQueryClient používá k dotazování metrik koncový bod Azure Resource Manager (ARM), takže při použití tohoto klienta budete potřebovat odpovídající koncový bod správy pro váš cloud. To se může v budoucnu změnit.

Spusťte dotaz.

Příklady dotazů na protokoly a metriky najdete v části Příklady .

Klíčové koncepty

Protokoluje omezení rychlosti dotazů a omezování.

Služba Log Analytics použije omezování, když je frekvence požadavků příliš vysoká. Omezení, jako je například maximální počet vrácených řádků, se použijí také u dotazů Kusto. Další informace najdete v tématu Rozhraní API pro dotazy.

Pokud spouštíte dotaz na dávkové protokoly, omezený požadavek vrátí LogsQueryError objekt . Hodnota objektu code bude ThrottledError.

Struktura dat metrik

Každá sada hodnot metrik je časová řada s následujícími charakteristikami:

  • Čas shromáždění hodnoty
  • Prostředek přidružený k hodnotě
  • Obor názvů, který funguje jako kategorie metriky
  • Název metriky
  • Samotná hodnota
  • Některé metriky můžou mít více dimenzí, jak je popsáno v tématu multidimenzionální metriky. Vlastní metriky můžou mít až 10 dimenzí.

Příklady

Dotaz na protokoly

Tento příklad ukazuje, jak dotazovat pracovní prostor služby Log Analytics. Ke zpracování odpovědi a jejímu zobrazení v tabulkové podobě se používá knihovna pandas . Pokud se rozhodnete pandas nepoužívat, projděte si ukázky .

Zadání časového rozsahu

Parametr timespan určuje dobu, po kterou se má dotazovat na data. Tato hodnota může být jedna z následujících:

  • A timedelta
  • a timedelta a počáteční datum a čas
  • počáteční datum a čas/koncový datetime

Příklad:

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)

Zpracování odpovědi na dotaz na protokoly

Rozhraní query_workspace API vrátí objekt LogsQueryResult nebo LogsQueryPartialResult . Rozhraní batch_query API vrátí seznam, který může obsahovat LogsQueryResultobjekty , LogsQueryPartialResulta LogsQueryError . Tady je hierarchie odpovědi:

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

Jako LogsQueryResult pohodlí přímo iteruje přes tabulku. Pokud chcete například zpracovat odpověď na protokoly s tabulkami a zobrazit ji pomocí knihovny pandas:

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

Úplnou ukázku najdete tady.

Podobně jako při zpracování odpovědi dotazu na dávkové protokoly:

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

Úplnou ukázku najdete tady.

Dotaz na dávkové protokoly

Následující příklad ukazuje odesílání více dotazů najednou pomocí rozhraní API dávkových dotazů. Dotazy mohou být reprezentovány jako seznam LogsBatchQuery objektů nebo slovník. V tomto příkladu se používá předchozí přístup.

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)

Dotaz na protokoly prostředků

Následující příklad ukazuje, jak dotazovat protokoly přímo z prostředku Azure bez použití pracovního prostoru služby Log Analytics. Tady se query_resource místo query_workspacepoužije metoda a místo ID pracovního prostoru se předá identifikátor prostředku Azure (např. /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)

Pokročilé scénáře dotazů na protokoly

Nastavení časového limitu dotazu na protokoly

Následující příklad ukazuje nastavení časového limitu serveru v sekundách. Pokud dotaz trvá déle, než je uvedený časový limit, dojde k vypršení časového limitu brány. Výchozí hodnota je 180 sekund a dá se nastavit až na 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
    )

Dotazování na více pracovních prostorů

Stejný dotaz na protokoly je možné spustit napříč několika pracovními prostory služby Log Analytics. Kromě dotazu Kusto se vyžadují následující parametry:

  • workspace_id – ID prvního (primárního) pracovního prostoru.
  • additional_workspaces – Seznam pracovních prostorů s výjimkou pracovního prostoru zadaného v parametru workspace_id . Položky seznamu parametru se mohou skládat z následujících formátů identifikátorů:
    • Kvalifikované názvy pracovních prostorů
    • ID pracovního prostoru
    • ID prostředků Azure

Například následující dotaz se spustí ve třech pracovních prostorech:

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

Úplnou ukázku najdete tady.

Zahrnout statistiky

Získání statistik provádění dotazů na protokoly, jako je využití procesoru a paměti:

  1. Nastavte include_statistics parametr na True.
  2. Přístup k statistics poli uvnitř objektu LogsQueryResult

Následující příklad vypíše čas provedení dotazu:

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 odpovídá dict nezpracované odpovědi JSON a jeho struktura se může lišit podle dotazu. Statistiky se nacházejí ve query vlastnosti . Příklad:

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

Zahrnout vizualizaci

Získání dat vizualizace pro dotazy na protokoly pomocí operátoru vykreslování:

  1. Nastavte include_visualization vlastnost na True.
  2. Přístup k visualization poli uvnitř objektu LogsQueryResult

Příklad:

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 odpovídá dict nezpracované odpovědi JSON a jeho struktura se může lišit podle dotazu. Příklad:

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

Dotaz na metriky

Následující příklad získá metriky pro odběr Event Gridu. Identifikátor URI prostředku odpovídá tématu Event Gridu.

Identifikátor URI prostředku musí být identifikátorem URI prostředku, pro který se metriky dotazují. Obvykle je ve formátu /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Vyhledání identifikátoru URI prostředku:

  1. V Azure Portal přejděte na stránku prostředku.
  2. V okně Přehled vyberte odkaz Zobrazení JSON .
  3. Ve výsledném formátu JSON zkopírujte hodnotu id vlastnosti .

POZNÁMKA: Metriky se vrací v pořadí odeslaných 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)

Zpracování odpovědi na dotazy na metriky

Rozhraní API pro dotazy na metriky MetricsQueryResult vrátí objekt . Objekt MetricsQueryResult obsahuje vlastnosti, jako je seznam Metricobjektů granularitytypu , namespacea timespan. Seznam Metric objektů je přístupný pomocí parametru metrics . Každý Metric objekt v tomto seznamu obsahuje seznam TimeSeriesElement objektů. Každý TimeSeriesElement objekt obsahuje data vlastnosti a metadata_values . Ve vizuální podobě se hierarchie objektů odpovědi podobá následující struktuře:

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)

Příklad zpracování odpovědi

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

Řešení potíží

Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v našem průvodci odstraňováním potíží.

Další kroky

Další informace o službě Azure Monitor najdete v dokumentaci ke službě Azure Monitor.

Ukázky

Následující ukázky kódu ukazují běžné scénáře s klientskou knihovnou dotazů služby Azure Monitor.

Ukázky dotazů protokolů

Ukázky dotazů na metriky

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete v cla.microsoft.com.

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pomocí našeho cla to budete muset provést ve všech úložištích pouze jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.