Azure Monitor Query ügyfélkódtár a Pythonhoz – 1.2.0-s verzió

  • Cikk

Az Azure Monitor Query ügyféloldali kódtára írásvédett lekérdezések végrehajtására szolgál az Azure Monitor két adatplatformján:

  • Naplók – Napló- és teljesítményadatokat gyűjt és rendszerez a figyelt erőforrásokból. A különböző forrásokból származó adatok, például az Azure-szolgáltatások platformnaplói, a virtuálisgép-ügynökök napló- és teljesítményadatai, valamint az alkalmazásokból származó használati és teljesítményadatok egyetlen Azure Log Analytics-munkaterületbe összesítve hozhatók létre. A különböző adattípusok együtt elemezhetők a Kusto lekérdezésnyelv használatával.
  • Metrikák – Numerikus adatokat gyűjt a figyelt erőforrásokból egy idősor-adatbázisba. A metrikák olyan numerikus értékek, amelyeket rendszeres időközönként gyűjtünk össze, és a rendszer bizonyos aspektusait írják le egy adott időpontban. A metrikák egyszerűek, és képesek közel valós idejű forgatókönyvek támogatására, így hasznosak a riasztásokhoz és a problémák gyors észleléséhez.

Erőforrások:

Első lépések

Előfeltételek

A csomag telepítése

Telepítse a Pythonhoz készült Azure Monitor Query ügyfélkódtárat a pip használatával:

pip install azure-monitor-query

Az ügyfél létrehozása

A naplók vagy metrikák lekérdezéséhez hitelesített ügyfél szükséges. A kódtár az ügyfelek szinkron és aszinkron formáit is tartalmazza. A hitelesítéshez hozzon létre egy token hitelesítőadat-példányt. Használja ezt a példányt a vagy MetricsQueryClienta LogsQueryClient létrehozásakor. Az alábbi példák az azure-identity csomagból származnakDefaultAzureCredential.

Szinkron ügyfelek

Vegyük az alábbi példát, amely szinkron ügyfeleket hoz létre a naplók és a metrikák lekérdezéséhez:

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

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

Aszinkron ügyfelek

A lekérdezési ügyfél API-k aszinkron formái a .aio-suffixed névtérben találhatók. Például:

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)

Ügyfelek konfigurálása nem nyilvános Azure-felhőkhöz

Alapértelmezés szerint a LogsQueryClient és MetricsQueryClient a nyilvános Azure-felhőhöz való csatlakozásra vannak konfigurálva. Ezek úgy konfigurálhatók, hogy nem nyilvános Azure-felhőkhöz csatlakozzanak a megfelelő endpoint argumentum megadásával: Például:

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

Megjegyzés: Jelenleg MetricsQueryClient az Azure Resource Manager (ARM) végpontot használja a metrikák lekérdezéséhez, ezért az ügyfél használatakor szüksége lesz a felhő megfelelő felügyeleti végpontjára. Ez a jövőben változhat.

Hajtsa végre a lekérdezést

Példák a Naplók és metrikák lekérdezésekre: Példák szakasz.

Fő fogalmak

Naplózza a lekérdezési sebesség korlátait és szabályozását

A Log Analytics szolgáltatás szabályozást alkalmaz, ha a kérések száma túl magas. A kusto-lekérdezésekre a rendszer korlátozásokat alkalmaz, például a visszaadott sorok maximális számát. További információ: Query API.

Ha kötegelt naplók lekérdezését hajtja végre, egy szabályozott kérés egy objektumot LogsQueryError ad vissza. Az objektum code értéke .ThrottledError

Metrikák adatstruktúrája

A metrikaértékek minden halmaza egy idősor, amely a következő jellemzőkkel rendelkezik:

  • Az érték gyűjtésének időpontja
  • Az értékhez társított erőforrás
  • A metrika kategóriájaként működő névtér
  • Metrikanév
  • Maga az érték
  • Egyes metrikák több dimenzióval is rendelkezhetnek a többdimenziós metrikákban leírtak szerint. Az egyéni metrikák legfeljebb 10 dimenzióval rendelkezhetnek.

Példák

Naplók lekérdezése

Ez a példa bemutatja, hogyan kérdezhet le egy Log Analytics-munkaterületet. A válasz kezeléséhez és táblázatos formában való megtekintéséhez a pandas-kódtárat használja a rendszer. Tekintse meg a mintákat , ha úgy dönt, hogy nem használja a pandast.

Időtartomány megadása

A timespan paraméter határozza meg az adatok lekérdezésének időtartamát. Ez az érték a következők egyike lehet:

  • A timedelta
  • a timedelta és egy kezdő dátum/idő
  • a start datetime/end datetime

Például:

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)

Naplók lekérdezési válaszának kezelése

Az query_workspace API egy LogsQueryResult vagy egy objektumot LogsQueryPartialResult ad vissza. Az batch_query API egy listát ad vissza, amely tartalmazhat LogsQueryResult, LogsQueryPartialResultés LogsQueryError objektumokat. A válasz hierarchiája a következő:

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

A LogsQueryResult közvetlenül a táblázat fölé viszi a kényelmet. Ha például táblákkal szeretné kezelni a naplók lekérdezési válaszát, és pandas használatával szeretné megjeleníteni:

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

A teljes minta itt található.

Hasonló módon a kötegelt naplók lekérdezési válaszának kezelése:

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

A teljes minta itt található.

Batch-naplók lekérdezése

Az alábbi példa több lekérdezés egyidejű küldését mutatja be a batch query API használatával. A lekérdezések objektumlistaként LogsBatchQuery vagy szótárként is megjeleníthetők. Ez a példa a korábbi megközelítést használja.

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)

Erőforrásnapló-lekérdezés

Az alábbi példa bemutatja, hogyan kérdezhet le naplókat közvetlenül egy Azure-erőforrásból Log Analytics-munkaterület használata nélkül. Itt a metódust használja query_workspacea query_resource helyett, és munkaterület-azonosító helyett egy Azure-erőforrás-azonosítót ad át (pl. /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)

Speciális naplók lekérdezési forgatókönyvei

Naplók lekérdezési időtúllépésének beállítása

Az alábbi példa egy kiszolgáló időtúllépésének másodpercben történő beállítását mutatja be. Az átjáró időtúllépése akkor lép fel, ha a lekérdezés több időt vesz igénybe, mint az említett időtúllépés. Az alapértelmezett érték 180 másodperc, és 10 percre (600 másodpercre) állítható be.

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
    )

Több munkaterület lekérdezése

Ugyanazt a napló lekérdezést több Log Analytics-munkaterületen is végrehajthatja. A Kusto-lekérdezés mellett a következő paraméterekre van szükség:

  • workspace_id – Az első (elsődleges) munkaterület azonosítója.
  • additional_workspaces – A munkaterületek listája, a paraméterben workspace_id megadott munkaterület kivételével. A paraméter listaelemei a következő azonosítóformátumokból állhatnak:
    • Minősített munkaterületnevek
    • Munkaterület-azonosítók
    • Azure-erőforrásazonosítók

A következő lekérdezés például három munkaterületen fut:

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

A teljes minta itt található.

Statisztika belefoglalása

Naplók lekérdezés-végrehajtási statisztikáinak lekérése, például a processzor- és memóriahasználat:

  1. Állítsa a paramétert a include_statistics értékre True.
  2. statistics Az objektumon belüli LogsQueryResult mező elérése.

Az alábbi példa a lekérdezés végrehajtási idejét nyomtatja ki:

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

A statistics mező egy dict olyan mező, amely megfelel a nyers JSON-válasznak, és struktúrája lekérdezésenként változhat. A statisztikák a tulajdonságon query belül találhatók. Például:

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

Vizualizáció belefoglalása

A naplók lekérdezéseinek vizualizációs adatainak lekérése a renderelési operátorral:

  1. Állítsa a tulajdonságot a include_visualization értékre True.
  2. visualization Az objektumon belüli LogsQueryResult mező elérése.

Például:

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

A visualization mező egy dict olyan mező, amely megfelel a nyers JSON-válasznak, és struktúrája lekérdezésenként változhat. Például:

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

Metrikák lekérdezése

Az alábbi példa beolvassa egy Event Grid-előfizetés metrikáit. Az erőforrás URI-ja egy Event Grid-témakör URI-ja.

Az erőforrás URI-jának annak az erőforrásnak kell lennie, amelyhez a metrikákat lekérdezik. Általában a formátuma /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Az erőforrás URI-jának megkeresése:

  1. Lépjen az erőforrás lapjára a Azure Portal.
  2. Az Áttekintés panelen válassza a JSON-nézet hivatkozást.
  3. Az eredményként kapott JSON-fájlban másolja ki a id tulajdonság értékét.

MEGJEGYZÉS: A metrikákat a rendszer az elküldött metric_names sorrendjében adja vissza.

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)

Metrikák lekérdezési válaszának kezelése

A metrika lekérdezési API egy MetricsQueryResult objektumot ad vissza. Az MetricsQueryResult objektum olyan tulajdonságokat tartalmaz, mint a -typed objektumok listája Metric, granularitya , namespaceés timespana . Az Metric objektumok listája a metrics param használatával érhető el. A lista minden Metric objektuma tartalmaz egy objektumlistát TimeSeriesElement . Minden TimeSeriesElement objektum tartalmaz data és metadata_values tulajdonságokat. Vizuális formában a válasz objektumhierarchiája a következő struktúrához hasonlít:

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élda a válasz kezelésére

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

Hibaelhárítás

A különböző hibaforgatókönyvek diagnosztizálásával kapcsolatos részletekért tekintse meg a hibaelhárítási útmutatónkat .

Következő lépések

Az Azure Monitorral kapcsolatos további információkért tekintse meg az Azure Monitor szolgáltatás dokumentációját.

Példák

Az alábbi kódminták az Azure Monitor Query ügyfélkódtárával kapcsolatos gyakori forgatókönyveket mutatják be.

Naplózza a lekérdezési mintákat

Metrikák lekérdezési mintái

Közreműködés

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. A részletekért látogasson el a cla.microsoft.com.

A lekéréses kérelmek elküldésekor egy CLA-robot automatikusan meghatározza, hogy kell-e biztosítania CLA-t, és megfelelően kitölti a lekéréses kérelmet (például címke, megjegyzés). Egyszerűen csak kövesse a robot által megadott utasításokat. Ezt csak egyszer kell elvégeznie az összes adattárban a CLA használatával.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.