Python için Azure İzleyici Sorgusu istemci kitaplığı - sürüm 1.2.0
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:
- Kaynak kodu
- Paket (PyPI)
- Paket (Conda)
- API başvuru belgeleri
- Hizmet belgeleri
- Örnekler
- Değişiklik günlüğü
Başlarken
Önkoşullar
- Python 3.7 veya üzeri
- Azure aboneliği
- Azure Kimlik kitaplığı kimlik bilgisi türü gibi bir TokenCredential uygulaması.
- Günlükleri sorgulamak için bir Azure Log Analytics çalışma alanı gerekir.
- Ölçümleri sorgulamak için her türlü Azure kaynağına (Depolama Hesabı, Key Vault, Cosmos DB vb.) ihtiyacınız vardır.
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 MetricsQueryClient
oluş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 .aio
bulunur. Ö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
- Batch günlükleri sorgusu
- Kaynak günlükleri sorgusu
- Gelişmiş günlükler sorgu senaryoları
- Ölçüm sorgusu
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, , LogsQueryPartialResult
ve LogsQueryError
nesnelerini içerebilen LogsQueryResult
bir 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_workspace
kullanı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ınworkspace_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:
- parametresini
include_statistics
olarakTrue
ayarlayın. - Nesnenin
statistics
içindeki alana erişinLogsQueryResult
.
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:
include_visualization
özelliğini olarakTrue
ayarlayın.- Nesnenin
visualization
içindeki alana erişinLogsQueryResult
.
Ö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:
- Azure portal kaynağınızın sayfasına gidin.
- Genel Bakış dikey penceresinde JSON Görünümü bağlantısını seçin.
- 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 Metric
granularity
namespace
listesi 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
- LogsQueryClient ile tek bir sorgu gönderme ve yanıtı tablo olarak işleme (zaman uyumsuz örnek)
- LogsQueryClient ile tek bir sorgu gönderme ve yanıtı anahtar-değer biçiminde işleme
- LogsQueryClient ile pandas olmadan tek bir sorgu gönderme
- Birden çok çalışma alanında LogsQueryClient ile tek bir sorgu gönderme
- LogsQueryClient ile birden çok sorgu gönderme
- Sunucu zaman aşımını kullanarak LogsQueryClient ile tek bir sorgu gönderme
Ölçüm sorgu örnekleri
- MetricsQueryClient kullanarak sorgu gönderme (zaman uyumsuz örnek)
- Ölçüm ad alanlarının listesini alma (zaman uyumsuz örnek)
- Ölçüm tanımlarının listesini alma (zaman uyumsuz örnek)
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 .
Azure SDK for Python
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin