مكتبة عميل استعلام Azure Monitor ل Python - الإصدار 1.2.0

تستخدم مكتبة عميل استعلام Azure Monitor لتنفيذ استعلامات للقراءة فقط مقابل النظامين الأساسيين للبيانات في Azure Monitor:

• السجلات - يجمع وينظم بيانات السجل والأداء من الموارد المراقبة. يمكن دمج البيانات من مصادر مختلفة مثل سجلات النظام الأساسي من خدمات Azure وبيانات السجل والأداء من عوامل الأجهزة الظاهرية وبيانات الاستخدام والأداء من التطبيقات في مساحة عمل Azure Log Analytics واحدة. يمكن تحليل أنواع البيانات المختلفة معا باستخدام لغة استعلام Kusto.
• المقاييس - يجمع البيانات الرقمية من الموارد المراقبة في قاعدة بيانات سلسلة زمنية. القياسات عبارة عن قيم عددية تُجمَّع على فترات زمنية منتظمة وتصف بعض جوانب النظام في وقتٍ معينٍ. المقاييس خفيفة الوزن وقادرة على دعم سيناريوهات قريبة من الوقت الحقيقي، ما يجعلها مفيدة للتنبيه والكشف السريع عن المشكلات.

الموارد:

• تعليمة برمجية مصدر
• حزمة (PyPI)
• حزمة (Conda)
• الوثائق المرجعية لواجهة برمجة التطبيقات
• وثائق الخدمة
• عينات
• سجل التغيير

الشروع في العمل

المتطلبات الأساسية

• Python 3.7 أو أحدث
• اشتراك Azure
• تطبيق TokenCredential ، مثل نوع بيانات اعتماد مكتبة هوية Azure.
• للاستعلام عن السجلات، تحتاج إلى مساحة عمل Azure Log Analytics.
• للاستعلام عن المقاييس، تحتاج إلى مورد Azure من أي نوع (حساب التخزين، Key Vault، Cosmos DB، وما إلى ذلك).

تثبيت الحِزَمة

قم بتثبيت مكتبة عميل Azure Monitor Query ل Python باستخدام pip:

pip install azure-monitor-query

إنشاء العميل

مطلوب عميل مصادق عليه للاستعلام عن السجلات أو المقاييس. تتضمن المكتبة كلا من النماذج المتزامنة وغير المتزامنة للعملاء. للمصادقة، أنشئ مثيلا لبيانات اعتماد الرمز المميز. استخدم هذا المثيل عند إنشاء أو LogsQueryClientMetricsQueryClient. تستخدم DefaultAzureCredential الأمثلة التالية من حزمة azure-identity .

العملاء المتزامنون

ضع في اعتبارك المثال التالي، الذي ينشئ عملاء متزامنين لكل من استعلام السجلات والمقاييس:

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

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

عملاء غير متزامنين

يتم العثور على النماذج غير المتزامنة لواجهات برمجة تطبيقات عميل الاستعلام في .aioمساحة الاسم -اللاحقة. على سبيل المثال:

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)

تكوين العملاء لسحب Azure غير العامة

بشكل افتراضي، LogsQueryClientMetricsQueryClient ويتم تكوينهما للاتصال بسحابة Azure العامة. يمكن تكوين هذه للاتصال بسحابة Azure غير العامة عن طريق تمرير الوسيطة الصحيحة endpoint : على سبيل المثال:

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

ملاحظة: حاليا، MetricsQueryClient تستخدم نقطة نهاية Azure Resource Manager (ARM) للاستعلام عن المقاييس، لذلك ستحتاج إلى نقطة نهاية الإدارة المقابلة للسحابة الخاصة بك عند استخدام هذا العميل. وهذا عرضة للتغيير في المستقبل.

تنفيذ الاستعلام

للحصول على أمثلة على استعلامات السجلات والمقاييس، راجع قسم الأمثلة .

المفاهيم الرئيسية

سجلات حدود معدل الاستعلام والتقييد

تطبق خدمة Log Analytics التقييد عندما يكون معدل الطلب مرتفعا جدا. يتم أيضا تطبيق الحدود، مثل الحد الأقصى لعدد الصفوف التي تم إرجاعها، على استعلامات Kusto. لمزيد من المعلومات، راجع واجهة برمجة تطبيقات الاستعلام.

إذا كنت تقوم بتنفيذ استعلام سجلات دفعية، فسيرجع طلب مقيد كائنا LogsQueryError . ستكون ThrottledErrorقيمة هذا الكائن code هي .

بنية بيانات المقاييس

كل مجموعة من قيم القياس هي سلسلة زمنية ذات الخصائص التالية:

• وقت تجميع القيمة
• المورد المقترن بالقيمة
• مساحة الاسم التي تعمل كفئة للقياس
• اسم القياس
• القيمة نفسها
• قد يكون لبعض المقاييس أبعاد متعددة كما هو موضح في المقاييس متعددة الأبعاد. يمكن أن تحتوي المقاييس المخصصة على ما يصل إلى 10 أبعاد.

أمثلة

• استعلام السجلات
  • تحديد الفترة الزمنية
  • معالجة استجابة استعلام السجلات
• استعلام سجلات الدفعات
• استعلام سجلات الموارد
• سيناريوهات استعلام السجلات المتقدمة
  • تعيين مهلة استعلام السجلات
  • الاستعلام عن مساحات عمل متعددة
  • تضمين الإحصائيات
  • تضمين المرئيات
• استعلام المقاييس
  • معالجة استجابة استعلام المقاييس
  • مثال على معالجة الاستجابة

استعلام السجلات

يوضح هذا المثال كيفية الاستعلام عن مساحة عمل Log Analytics. للتعامل مع الاستجابة وعرضها في نموذج جدولي، يتم استخدام مكتبة pandas . راجع العينات إذا اخترت عدم استخدام pandas.

تحديد الفترة الزمنية

timespan تحدد المعلمة المدة الزمنية للاستعلام عن البيانات. يمكن أن تكون هذه القيمة واحدة مما يلي:

• أ timedelta
• أ timedelta وتاريخ البدء
• تاريخ البدء/وقت الانتهاء

على سبيل المثال:

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)

معالجة استجابة استعلام السجلات

query_workspace ترجع واجهة برمجة التطبيقات إما كائنا LogsQueryResultLogsQueryPartialResult أو . batch_query تقوم واجهة برمجة التطبيقات بإرجاع قائمة قد تحتوي على LogsQueryResultكائنات LogsQueryPartialResultو وLogsQueryError. فيما يلي تسلسل هرمي للاستجابة:

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

يتكرر LogsQueryResult مباشرة فوق الجدول كوسيلة للراحة. على سبيل المثال، للتعامل مع استجابة استعلام السجلات باستخدام الجداول وعرضها باستخدام pandas:

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

يمكن العثور على عينة كاملة هنا.

بطريقة مماثلة، للتعامل مع استجابة استعلام سجلات الدفعات:

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

يمكن العثور على عينة كاملة هنا.

استعلام سجلات الدفعات

يوضح المثال التالي إرسال استعلامات متعددة في نفس الوقت باستخدام واجهة برمجة تطبيقات استعلام الدفعة. يمكن تمثيل الاستعلامات إما كقوائم كائنات LogsBatchQuery أو قاموس. يستخدم هذا المثال النهج السابق.

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)

استعلام سجلات الموارد

يوضح المثال التالي كيفية الاستعلام عن السجلات مباشرة من مورد Azure دون استخدام مساحة عمل Log Analytics. هنا، query_resource يتم استخدام الأسلوب بدلا من query_workspace، وبدلا من معرف مساحة العمل، يتم تمرير معرف مورد Azure (على سبيل المثال /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)

سيناريوهات استعلام السجلات المتقدمة

تعيين مهلة استعلام السجلات

يوضح المثال التالي تعيين مهلة خادم بالثوان. يتم رفع مهلة البوابة إذا كان الاستعلام يستغرق وقتا أطول من المهلة المذكورة. الإعداد الافتراضي هو 180 ثانية ويمكن إعداده حتى 10 دقائق (600 ثانية).

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
    )

الاستعلام عن مساحات عمل متعددة

يمكن تنفيذ نفس استعلام السجلات عبر مساحات عمل Log Analytics متعددة. بالإضافة إلى استعلام Kusto، المعلمات التالية مطلوبة:

• workspace_id - معرف مساحة العمل الأول (الأساسي).
• additional_workspaces - قائمة بمساحات العمل، باستثناء مساحة العمل المتوفرة في المعلمة workspace_id . قد تتكون عناصر قائمة المعلمة من تنسيقات المعرف التالية:
  • أسماء مساحات العمل المؤهلة
  • معرفات مساحة العمل
  • معرفات موارد Azure

على سبيل المثال، يتم تنفيذ الاستعلام التالي في ثلاث مساحات عمل:

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

يمكن العثور على عينة كاملة هنا.

تضمين الإحصائيات

للحصول على إحصائيات تنفيذ استعلام السجلات، مثل استهلاك وحدة المعالجة المركزية والذاكرة:

1. عين include_statistics المعلمة إلىTrue
2. statistics الوصول إلى الحقل داخل LogsQueryResult الكائن.

يطبع المثال التالي وقت تنفيذ الاستعلام:

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 الحقل هو dict الذي يتوافق مع استجابة JSON الأولية، ويمكن أن تختلف بنيته حسب الاستعلام. يتم العثور على الإحصائيات داخل الخاصية query . على سبيل المثال:

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

تضمين المرئيات

للحصول على بيانات المرئيات لاستعلامات السجلات باستخدام عامل تشغيل العرض:

1. اضبط الخاصية include_visualization على True.
2. visualization الوصول إلى الحقل داخل LogsQueryResult الكائن.

على سبيل المثال:

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 الحقل هو dict الذي يتوافق مع استجابة JSON الأولية، ويمكن أن تختلف بنيته حسب الاستعلام. على سبيل المثال:

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

استعلام المقاييس

يحصل المثال التالي على مقاييس لاشتراك Event Grid. عنوان URI للمورد هو موضوع Event Grid.

يجب أن يكون عنوان URI للمورد هو المورد الذي يتم الاستعلام عن المقاييس له. عادة ما يكون بالتنسيق /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

للعثور على URI للمورد:

1. انتقل إلى صفحة المورد في مدخل Microsoft Azure.
2. من جزء Overview ، حدد رابط JSON View .
3. في JSON الناتج، انسخ قيمة الخاصية id .

ملاحظة: يتم إرجاع المقاييس بترتيب metric_names المرسلة.

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)

معالجة استجابة استعلام المقاييس

ترجع واجهة برمجة تطبيقات استعلام المقاييس كائنا MetricsQueryResult . MetricsQueryResult يحتوي الكائن على خصائص مثل قائمة Metricالكائنات التي تم كتابتها و granularitynamespaceو وtimespan. Metric يمكن الوصول إلى قائمة الكائنات باستخدام المعلمة metrics . يحتوي كل Metric كائن في هذه القائمة على قائمة TimeSeriesElement الكائنات. يحتوي كل TimeSeriesElement كائن على data خصائص و metadata_values . في النموذج المرئي، يشبه التسلسل الهرمي للكائن للاستجابة البنية التالية:

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)

مثال على معالجة الاستجابة

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

استكشاف الأخطاء وإصلاحها

راجع دليل استكشاف الأخطاء وإصلاحها للحصول على تفاصيل حول كيفية تشخيص سيناريوهات الفشل المختلفة.

الخطوات التالية

لمعرفة المزيد حول Azure Monitor، راجع وثائق خدمة Azure Monitor.

عينات

تظهر نماذج التعليمات البرمجية التالية سيناريوهات شائعة مع مكتبة عميل Azure Monitor Query.

نماذج استعلام السجلات

• إرسال استعلام واحد باستخدام LogsQueryClient ومعالجة الاستجابة كجدول (نموذج غير متزامن)
• إرسال استعلام واحد باستخدام LogsQueryClient ومعالجة الاستجابة في نموذج قيمة المفتاح
• إرسال استعلام واحد باستخدام LogsQueryClient بدون pandas
• إرسال استعلام واحد باستخدام LogsQueryClient عبر مساحات عمل متعددة
• إرسال استعلامات متعددة باستخدام LogsQueryClient
• إرسال استعلام واحد باستخدام LogsQueryClient باستخدام مهلة الخادم

نماذج استعلام المقاييس

• إرسال استعلام باستخدام MetricsQueryClient (نموذج غير متزامن)
• الحصول على قائمة بمساحات أسماء المقاييس (عينة غير متزامنة)
• الحصول على قائمة بتعريفات القياس (عينة غير متزامنة)

المساهمة

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. للحصول على التفاصيل، تفضل بزيارة cla.microsoft.com.

عند إرسال طلب سحب، سيحدد روبوت CLA-bot تلقائيًا ما إذا كنت بحاجة إلى تقديم CLA وتزيين العلاقات العامة بشكل مناسب (على سبيل المثال، التسمية أو التعليق). ما عليك سوى اتباع التعليمات التي يقدمها الروبوت. ستحتاج إلى القيام بذلك مرة واحدة فقط عبر جميع المستودعات باستخدام CLA الخاص بنا.

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة المتداولة حول قواعد السلوك أو الاتصال opencode@microsoft.com بأي أسئلة أو تعليقات إضافية.