Pustaka klien Azure Monitor Query untuk Python - versi 1.0.3

Artikel
11/16/2022
8 menit untuk membaca

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 sangat berguna untuk memperingatkan dan mendeteksi masalah dengan cepat.

Sumber Daya:

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 telah berakhir pada 01 Januari 2022. Untuk informasi dan pertanyaan lebih lanjut, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Prasyarat

Python 3.6 atau yang lebih baru
Langganan Azure
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)

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
Skenario kueri log tingkat lanjut
- Mengatur batas waktu kueri log
- Mengkueri beberapa ruang kerja
Kueri metrik
- Menangani respons kueri metrik
- Contoh respons penanganan

Kueri log

Contoh ini memperlihatkan mendapatkan kueri 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.message)
    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
    |---column_types

LogsQueryPartialResult
|---statistics
|---visualization
|---partial_error (a `LogsQueryError` object)
    |---code
    |---message
    |---status
|---partial_data (list of `LogsTable` objects)
    |---name
    |---rows
    |---columns
    |---column_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.message)
        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)

Skenario kueri log tingkat lanjut

Mengatur batas waktu kueri log

Contoh berikut menunjukkan pengaturan batas waktu server dalam hitung 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=None,
    server_timeout=1,
    )

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,
    additional_workspaces=['<workspace 2>', '<workspace 3>']
    )

Sampel lengkap dapat ditemukan di sini.

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:

Navigasi ke halaman sumber daya Anda di portal Azure.
Dari bilah Gambaran Umum , pilih tautan Tampilan JSON .
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

Aktifkan pencatat azure.monitor.query untuk mengumpulkan jejak dari pustaka.

Umum

Pustaka klien Monitor Query akan memunculkan pengecualian yang ditentukan di Azure Core.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP, seperti URL dan header, dicatat di tingkat .INFO

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasiazure-core referensi menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

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

Sampel kueri metrik

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.

Pustaka klien Azure Monitor Query untuk Python - versi 1.0.3

Pengelakan

Memulai

Prasyarat

Instal paketnya

Membuat klien

Klien sinkron

Klien asinkron

Mengeksekusi kueri

Konsep utama

Mencatat batas laju kueri dan pembatasan

Struktur data metrik

Contoh

Kueri log

Tentukan rentang waktu

Menangani respons kueri log

Kueri log batch

Skenario kueri log tingkat lanjut

Mengatur batas waktu kueri log

Mengkueri beberapa ruang kerja

Kueri metrik

Menangani respons kueri metrik

Contoh respons penanganan

Pemecahan Masalah

Umum

Pembuatan Log

Konfigurasi Opsional

Langkah berikutnya

Sampel

Sampel kueri log

Sampel kueri metrik

Berkontribusi

Sumber Daya Tambahan:

Sumber Daya Tambahan: