Pustaka klien Azure Monitor Query untuk Python - versi 1.2.0

Pustaka klien Azure Monitor Query digunakan untuk menjalankan kueri baca-saja terhadap dua platform data Azure Monitor:

• Log - Mengumpulkan dan mengatur data log dan performa dari sumber daya yang dipantau. Data dari berbagai sumber seperti log platform dari layanan Azure, data log dan performa dari agen komputer virtual, serta data penggunaan dan performa dari aplikasi dapat dikonsolidasikan ke dalam satu ruang kerja Azure Log Analytics. Berbagai jenis data dapat dianalisis bersama menggunakan Bahasa Kueri Kusto.
• Metrik - Mengumpulkan data numerik dari sumber daya yang dipantau ke dalam database rangkaian waktu. Metrik adalah nilai numerik yang dikumpulkan secara interval dan menggambarkan beberapa aspek sistem pada waktu tertentu. Metrik ringan dan mampu mendukung skenario mendekati real-time, membuatnya berguna untuk memperingatkan dan mendeteksi masalah dengan cepat.

Sumber Daya:

• Kode sumber
• Paket (PyPI)
• Paket (Conda)
• Dokumentasi referensi API
• Dokumentasi layanan
• Sampel
• Log perubahan

Memulai

Prasyarat

• Python 3.7 atau yang lebih baru
• Langganan Azure
• Implementasi TokenCredential , seperti jenis kredensial pustaka Azure Identity.
• Untuk mengkueri Log, Anda memerlukan ruang kerja Azure Log Analytics.
• Untuk mengkueri Metrik, Anda memerlukan sumber daya Azure dalam bentuk apa pun (Akun Penyimpanan, Key Vault, Cosmos DB, dll.).

Instal paketnya

Instal pustaka klien Azure Monitor Query untuk Python dengan pip:

pip install azure-monitor-query

Membuat klien

Klien yang diautentikasi diperlukan untuk mengkueri Log atau Metrik. Pustaka mencakup bentuk klien yang sinkron dan asinkron. Untuk mengautentikasi, buat instans kredensial token. Gunakan instans tersebut saat membuat LogsQueryClient atau MetricsQueryClient. Contoh berikut menggunakan DefaultAzureCredential dari paket azure-identity .

Klien sinkron

Pertimbangkan contoh berikut, yang membuat klien sinkron untuk kueri Log dan Metrik:

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

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

Klien asinkron

Bentuk asinkron dari API klien kueri ditemukan di .aionamespace layanan -akhiran. Contohnya:

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)

Mengonfigurasi klien untuk cloud Azure non-publik

Secara default, LogsQueryClient dan MetricsQueryClient dikonfigurasi untuk menyambungkan ke cloud Azure publik. Ini dapat dikonfigurasi untuk menyambungkan ke cloud Azure non-publik dengan meneruskan argumen yang benar endpoint : Misalnya:

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

Catatan: Saat ini, MetricsQueryClient menggunakan titik akhir Azure Resource Manager (ARM) untuk mengkueri metrik, sehingga Anda akan memerlukan titik akhir manajemen yang sesuai untuk cloud Anda saat menggunakan klien ini. Hal ini dapat berubah di masa depan.

Mengeksekusi kueri

Untuk contoh kueri Log dan Metrik, lihat bagian Contoh .

Konsep utama

Mencatat batas laju kueri dan pembatasan

Layanan Analitik Log menerapkan pembatasan saat tingkat permintaan terlalu tinggi. Batas, seperti jumlah maksimum baris yang dikembalikan, juga diterapkan pada kueri Kusto. Untuk informasi selengkapnya, lihat API Kueri.

Jika Anda menjalankan kueri log batch, permintaan yang dibatasi akan mengembalikan LogsQueryError objek. Nilai objek itu code akan menjadi ThrottledError.

Struktur data metrik

Setiap set nilai metrik adalah rangkaian waktu dengan karakteristik berikut:

• Waktu nilai dikumpulkan
• Sumber daya yang terkait dengan nilai
• Namespace yang bertindak seperti kategori untuk metrik
• Nama metrik
• Nilai itu sendiri
• Beberapa metrik mungkin memiliki beberapa dimensi seperti yang dijelaskan dalam metrik multi-dimensi. Metrik khusus dapat memiliki hingga 10 dimensi.

Contoh

• Kueri log
  • Tentukan rentang waktu
  • Menangani respons kueri log
• Kueri log batch
• Kueri log sumber daya
• Skenario kueri log tingkat lanjut
  • Mengatur batas waktu kueri log
  • Mengkueri beberapa ruang kerja
  • Sertakan statistik
  • Sertakan visualisasi
• Kueri metrik
  • Menangani respons kueri metrik
  • Contoh respons penanganan

Kueri log

Contoh ini memperlihatkan cara mengkueri ruang kerja Analitik Log. Untuk menangani respons dan menampilkannya dalam bentuk tabular, pustaka pandas digunakan. Lihat sampel jika Anda memilih untuk tidak menggunakan panda.

Tentukan rentang waktu

Parameter timespan menentukan durasi waktu untuk mengkueri data. Nilai ini bisa menjadi salah satu dari berikut ini:

• a timedelta
• timedelta dan tanggalwaktu mulai
• tanggalwaktu mulai/tanggalwaktu akhir

Contohnya:

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)

Menangani respons kueri log

query_workspace API mengembalikan objek LogsQueryResult atau LogsQueryPartialResult . batch_query API mengembalikan daftar yang mungkin berisi LogsQueryResultobjek , LogsQueryPartialResult, dan LogsQueryError . Berikut adalah hierarki respons:

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

Secara LogsQueryResult langsung melakukan iterasi di atas tabel sebagai kenyamanan. Misalnya, untuk menangani respons kueri log dengan tabel dan menampilkannya menggunakan panda:

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

Sampel lengkap dapat ditemukan di sini.

Dengan cara yang sama, untuk menangani respons kueri log batch:

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

Sampel lengkap dapat ditemukan di sini.

Kueri log batch

Contoh berikut menunjukkan pengiriman beberapa kueri secara bersamaan menggunakan API kueri batch. Kueri dapat direpresentasikan sebagai daftar LogsBatchQuery objek atau kamus. Contoh ini menggunakan pendekatan sebelumnya.

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)

Kueri log sumber daya

Contoh berikut menunjukkan cara mengkueri log langsung dari sumber daya Azure tanpa menggunakan ruang kerja Analitik Log. Di sini, query_resource metode ini digunakan alih-alih query_workspace, dan alih-alih ID ruang kerja, pengidentifikasi sumber daya Azure diteruskan (misalnya /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)

Skenario kueri log tingkat lanjut

Mengatur batas waktu kueri log

Contoh berikut menunjukkan pengaturan batas waktu server dalam detik. Batas waktu gateway dinaikkan jika kueri membutuhkan lebih banyak waktu daripada batas waktu yang disebutkan. Defaultnya adalah 180 detik dan dapat diatur hingga 10 menit (600 detik).

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
    )

Mengkueri beberapa ruang kerja

Kueri log yang sama dapat dijalankan di beberapa ruang kerja Analitik Log. Selain kueri Kusto, parameter berikut diperlukan:

• workspace_id - ID ruang kerja pertama (utama).
• additional_workspaces - Daftar ruang kerja, tidak termasuk ruang kerja yang disediakan dalam workspace_id parameter . Item daftar parameter mungkin terdiri dari format pengidentifikasi berikut:
  • Nama ruang kerja yang memenuhi syarat
  • ID ruang kerja
  • ID sumber daya Azure

Misalnya, kueri berikut dijalankan di tiga ruang kerja:

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

Sampel lengkap dapat ditemukan di sini.

Sertakan statistik

Untuk mendapatkan statistik eksekusi kueri log, seperti konsumsi CPU dan memori:

1. Set include_statistics parameter ke True.
2. Akses bidang di statistics dalam LogsQueryResult objek .

Contoh berikut mencetak waktu eksekusi kueri:

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

Bidang statistics adalah dict yang sesuai dengan respons JSON mentah, dan strukturnya dapat bervariasi menurut kueri. Statistik ditemukan dalam query properti . Contohnya:

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

Sertakan visualisasi

Untuk mendapatkan data visualisasi untuk kueri log menggunakan operator render:

1. Atur properti include_visualization ke True.
2. Akses bidang di visualization dalam LogsQueryResult objek .

Contohnya:

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

Bidang visualization adalah dict yang sesuai dengan respons JSON mentah, dan strukturnya dapat bervariasi menurut kueri. Contohnya:

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

Kueri metrik

Contoh berikut mendapatkan metrik untuk langganan Event Grid. URI sumber daya adalah topik Event Grid.

URI sumber daya harus merupakan sumber daya yang metriknya sedang dikueri. Biasanya formatnya /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Untuk menemukan URI sumber daya:

1. Navigasi ke halaman sumber daya Anda di portal Azure.
2. Dari bilah Gambaran Umum , pilih tautan Tampilan JSON .
3. Dalam JSON yang dihasilkan, salin nilai id properti .

CATATAN: Metrik dikembalikan dalam urutan metric_names dikirim.

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)

Menangani respons kueri metrik

API kueri metrik mengembalikan MetricsQueryResult objek . Objek MetricsQueryResult berisi properti seperti daftar Metricobjek -typed, granularity, , namespacedan timespan. Daftar Metric objek dapat diakses menggunakan metrics param. Setiap Metric objek dalam daftar ini berisi daftar TimeSeriesElement objek. Setiap TimeSeriesElement objek berisi data properti dan metadata_values . Dalam bentuk visual, hierarki objek respons menyerupai struktur berikut:

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)

Contoh respons penanganan

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

Pemecahan Masalah

Lihat panduan pemecahan masalah kami untuk detail tentang cara mendiagnosis berbagai skenario kegagalan.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang Azure Monitor, lihat dokumentasi layanan Azure Monitor.

Sampel

Sampel kode berikut menunjukkan skenario umum dengan pustaka klien Azure Monitor Query.

Sampel kueri log

• Mengirim satu kueri dengan LogsQueryClient dan menangani respons sebagai tabel (sampel asinkron)
• Mengirim satu kueri dengan LogsQueryClient dan menangani respons dalam bentuk nilai kunci
• Mengirim satu kueri dengan LogsQueryClient tanpa panda
• Mengirim satu kueri dengan LogsQueryClient di beberapa ruang kerja
• Mengirim beberapa kueri dengan LogsQueryClient
• Mengirim satu kueri dengan LogsQueryClient menggunakan batas waktu server

Sampel kueri metrik

• Mengirim kueri menggunakan MetricsQueryClient (sampel asinkron)
• Mendapatkan daftar namespace metrik (sampel asinkron)
• Mendapatkan daftar definisi metrik (sampel asinkron)

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repositori menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.