Python için Azure İzleyici Sorgusu istemci kitaplığı - sürüm 1.2.0

  • Makale

Azure İzleyici Sorgusu istemci kitaplığı, Azure İzleyici'nin iki veri platformunda salt okunur sorgular yürütmek için kullanılır:

  • Günlükler - İzlenen kaynaklardan günlük ve performans verilerini toplar ve düzenler. Azure hizmetlerinden platform günlükleri, sanal makine aracılarından günlük ve performans verileri ve uygulamalardan gelen kullanım ve performans verileri gibi farklı kaynaklardan gelen veriler tek bir Azure Log Analytics çalışma alanında birleştirilebilir. Çeşitli veri türleri Kusto Sorgu Dili kullanılarak birlikte analiz edilebilir.
  • Ölçümler - İzlenen kaynaklardan bir zaman serisi veritabanına sayısal veriler toplar. Ölçümler, düzenli aralıklarla toplanan ve belirli bir zamanda sistemin bazı yönlerini açıklayan sayısal değerlerdir. Ölçümler hafiftir ve gerçek zamanlıya yakın senaryoları destekleyerek sorunları uyarmak ve hızlı algılamak için kullanışlıdır.

Kaynaklar:

Başlarken

Önkoşullar

Paketi yükleme

Pip ile Python için Azure İzleyici Sorgusu istemci kitaplığını yükleyin:

pip install azure-monitor-query

İstemci oluşturma

Günlükleri veya Ölçümleri sorgulamak için kimliği doğrulanmış bir istemci gerekir. Kitaplık, istemcilerin hem zaman uyumlu hem de zaman uyumsuz biçimlerini içerir. Kimlik doğrulaması yapmak için belirteç kimlik bilgilerinin bir örneğini oluşturun. veya MetricsQueryClientoluştururken LogsQueryClient bu örneği kullanın. Aşağıdaki örnekler azure-identity paketinden kullanılırDefaultAzureCredential.

Zaman uyumlu istemciler

Hem Günlükler hem de Ölçümler sorgulaması için zaman uyumlu istemciler oluşturan aşağıdaki örneği göz önünde bulundurun:

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

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

Zaman uyumsuz istemciler

Sorgu istemcisi API'lerinin zaman uyumsuz formları -suffixed ad alanında .aiobulunur. Örnek:

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)

Genel olmayan Azure bulutları için istemcileri yapılandırma

varsayılan olarak LogsQueryClient ve MetricsQueryClient genel Azure buluta bağlanacak şekilde yapılandırılır. Bunlar, doğru endpoint bağımsız değişkeni geçirerek genel olmayan Azure bulutlarına bağlanacak şekilde yapılandırılabilir: Örneğin:

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

Not: Şu anda MetricsQueryClient ölçümleri sorgulamak için Azure Resource Manager (ARM) uç noktasını kullandığından, bu istemciyi kullanırken bulutunuz için karşılık gelen yönetim uç noktasına ihtiyacınız olacaktır. Bu durum gelecekte değişebilir.

Sorguyu yürütün

Günlükler ve Ölçümler sorgusu örnekleri için Örnekler bölümüne bakın.

Önemli kavramlar

Sorgu hızı sınırlarını ve azaltmayı günlüğe kaydeder

İstek oranı çok yüksek olduğunda Log Analytics hizmeti azaltma uygular. Döndürülen en fazla satır sayısı gibi sınırlar Kusto sorgularına da uygulanır. Daha fazla bilgi için bkz . Sorgu API'si.

Bir toplu iş günlükleri sorgusu yürütüyorsanız, kısıtlanmış bir istek bir LogsQueryError nesne döndürür. Bu nesnenin code değeri olacaktır ThrottledError.

Ölçüm veri yapısı

Her ölçüm değeri kümesi, aşağıdaki özelliklere sahip bir zaman serisidir:

  • Değerin toplandığı saat
  • Değerle ilişkili kaynak
  • Ölçüm için bir kategori gibi davranan bir ad alanı
  • Ölçüm adı
  • Değerin kendisi
  • Bazı ölçümlerin çok boyutlu ölçümlerde açıklandığı gibi birden çok boyutu olabilir. Özel ölçümlerin en fazla 10 boyutu olabilir.

Örnekler

Günlükler sorgusu

Bu örnekte Log Analytics çalışma alanının nasıl sorgu yapılacağı gösterilmektedir. Yanıtı işlemek ve tablo biçiminde görüntülemek için pandas kitaplığı kullanılır. Pandas kullanmamayı seçerseniz örneklere bakın.

Zaman aralığını belirtme

timespan parametresi, verilerin sorgulandığı süreyi belirtir. Bu değer aşağıdakilerden biri olabilir:

  • A timedelta
  • a timedelta ve start datetime
  • start datetime/end datetime

Örnek:

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)

Günlükleri işleme sorgu yanıtı

query_workspace API bir LogsQueryResult veya LogsQueryPartialResult nesnesi döndürür. batch_query API, , LogsQueryPartialResultve LogsQueryError nesnelerini içerebilen LogsQueryResultbir liste döndürür. Yanıtın hiyerarşisi aşağıdadır:

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

kolaylık LogsQueryResult sağlamak için doğrudan tablo üzerinde yinelenir. Örneğin, günlükleri işlemek için sorgu yanıtını tablolarla birlikte işleyip pandas kullanarak görüntüleyin:

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

Tam bir örnek burada bulunabilir.

Benzer şekilde, toplu iş günlükleri sorgu yanıtını işlemek için:

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

Tam bir örnek burada bulunabilir.

Batch günlükleri sorgusu

Aşağıdaki örnek, toplu sorgu API'sini kullanarak aynı anda birden çok sorgu göndermeyi gösterir. Sorgular, nesne listesi LogsBatchQuery veya sözlük olarak gösterilebilir. Bu örnekte eski yaklaşım kullanılır.

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)

Kaynak günlükleri sorgusu

Aşağıdaki örnekte Log Analytics çalışma alanı kullanılmadan günlükleri doğrudan bir Azure kaynağından sorgulama gösterilmektedir. query_resource Burada yöntemi yerine query_workspacekullanılır ve çalışma alanı kimliği yerine bir Azure kaynak tanımlayıcısı geçirilir (örneğin/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)

Gelişmiş günlükler sorgu senaryoları

Günlükleri ayarlama sorgusu zaman aşımı

Aşağıdaki örnekte sunucu zaman aşımının saniyeler içinde ayarlanması gösterilmektedir. Sorgu belirtilen zaman aşımından daha uzun sürerse ağ geçidi zaman aşımı oluşur. Varsayılan değer 180 saniyedir ve 10 dakikaya (600 saniye) kadar ayarlanabilir.

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
    )

Birden çok çalışma alanını sorgulama

Aynı günlük sorgusu birden çok Log Analytics çalışma alanında yürütülebilir. Kusto sorgusuna ek olarak aşağıdaki parametreler de gereklidir:

  • workspace_id - İlk (birincil) çalışma alanı kimliği.
  • additional_workspaces - Parametresinde sağlanan çalışma alanı dışında kalan çalışma alanlarının workspace_id listesi. Parametrenin liste öğeleri aşağıdaki tanımlayıcı biçimlerinden oluşabilir:
    • Nitelikli çalışma alanı adları
    • Çalışma Alanı Kimlikleri
    • Azure kaynak kimlikleri

Örneğin, aşağıdaki sorgu üç çalışma alanında yürütülür:

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

Tam bir örnek burada bulunabilir.

İstatistikleri dahil et

Günlükleri almak için CPU ve bellek tüketimi gibi sorgu yürütme istatistikleri:

  1. parametresini include_statistics olarak Trueayarlayın.
  2. Nesnenin statistics içindeki alana erişin LogsQueryResult .

Aşağıdaki örnek, sorgu yürütme süresini yazdırır:

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

statistics alanı, ham JSON yanıtına karşılık gelen bir dict alanıdır ve yapısı sorguya göre farklılık gösterebilir. İstatistikler özelliği içinde query bulunur. Örnek:

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

Görselleştirmeyi dahil et

İşleme işlecini kullanarak günlük sorgularının görselleştirme verilerini almak için:

  1. include_visualization özelliğini olarak Trueayarlayın.
  2. Nesnenin visualization içindeki alana erişin LogsQueryResult .

Örnek:

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

visualization alanı, ham JSON yanıtına karşılık gelen bir dict alanıdır ve yapısı sorguya göre farklılık gösterebilir. Örnek:

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

Ölçüm sorgusu

Aşağıdaki örnek bir Event Grid aboneliğinin ölçümlerini alır. Kaynak URI'sı bir Event Grid konusununkidir.

Kaynak URI'sinin ölçümlerin sorgulandığı kaynak olması gerekir. Normalde biçimindedir /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Kaynak URI'sini bulmak için:

  1. Azure portal kaynağınızın sayfasına gidin.
  2. Genel Bakış dikey penceresinde JSON Görünümü bağlantısını seçin.
  3. Sonuçta elde edilen JSON'da özelliğinin id değerini kopyalayın.

NOT: Ölçümler, gönderilen metric_names sırasına göre döndürülür.

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)

Ölçüm sorgu yanıtını işleme

Ölçüm sorgusu API'si bir MetricsQueryResult nesne döndürür. MetricsQueryResult nesnesi , ve timespan-typed nesnelerinin Metricgranularitynamespacelistesi gibi özellikler içerir. Metric Nesne listesine param kullanılarak metrics erişilebilir. Bu listedeki her Metric nesne bir nesne listesi TimeSeriesElement içerir. Her TimeSeriesElement nesne ve metadata_values özellikleri içerirdata. Görsel biçimde, yanıtın nesne hiyerarşisi aşağıdaki yapıya benzer:

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)

Yanıtı işleme örneği

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

Sorun giderme

Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzumuza bakın.

Sonraki adımlar

Azure İzleyici hakkında daha fazla bilgi edinmek için Azure İzleyici hizmeti belgelerine bakın.

Örnekler

Aşağıdaki kod örnekleri, Azure İzleyici Sorgusu istemci kitaplığıyla ilgili yaygın senaryoları gösterir.

Sorgu örneklerini günlüğe kaydeder

Ölçüm sorgu örnekleri

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bunu CLA'mızı kullanarak tüm depolarda yalnızca bir kez yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .