Поделиться через

Клиентская библиотека запросов Azure Monitor для Python — версия 1.2.0

  • Статья

Клиентская библиотека запросов Azure Monitor используется для выполнения запросов только для чтения к двум платформам данных Azure Monitor:

  • Журналы — собирает и упорядочивает данные журналов и производительности из отслеживаемых ресурсов. Данные из различных источников, таких как журналы платформы из служб Azure, журналы и данные о производительности из агентов виртуальных машин, а также данные об использовании и производительности из приложений, можно объединить в одну рабочую область Azure Log Analytics. Различные типы данных можно анализировать вместе с помощью язык запросов Kusto.
  • Метрики — собирает числовые данные из отслеживаемых ресурсов в базу данных временных рядов. Метрики — это числовые значения, которые собираются через регулярные интервалы и описывают определенный аспект ресурса на определенный момент времени. Метрики являются упрощенными и способны поддерживать сценарии практически в реальном времени, что делает их полезными для оповещения и быстрого обнаружения проблем.

Ресурсы:

Начало работы

Предварительные требования

Установка пакета

Установите клиентную библиотеку запросов Azure Monitor для Python с помощью pip:

pip install azure-monitor-query

Создание клиента

Для запроса журналов или метрик требуется клиент, прошедший проверку подлинности. Библиотека включает синхронные и асинхронные формы клиентов. Для проверки подлинности создайте экземпляр учетных данных маркера. Используйте этот экземпляр при создании LogsQueryClient или MetricsQueryClient. В следующих примерах используется 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)

Асинхронные клиенты

Асинхронные формы КЛИЕНТСКИХ API запросов находятся в пространстве имен с суффиксами .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, не являющихся общедоступными

По умолчанию LogsQueryClient и MetricsQueryClient настроены для подключения к общедоступному облаку 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. Дополнительные сведения см. в разделе API запросов.

Если вы выполняете запрос пакетных журналов, регулируемый запрос вернет LogsQueryError объект . Значение этого объекта code будет иметь значение ThrottledError.

Структура данных метрик

Каждый набор значений метрик представляет собой временные ряды со следующими характеристиками:

  • время получения значения;
  • Ресурс, связанный со значением
  • пространство имен, используемое в качестве категории метрики;
  • имя метрики;
  • само значение;
  • Некоторые метрики могут иметь несколько измерений, как описано в многомерных метриках. Пользовательские метрики могут иметь до 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 API возвращает объект LogsQueryResult или LogsQueryPartialResult . batch_query API возвращает список, который может содержать 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)

Полный пример можно найти здесь.

Запрос к журналам пакетной службы

В следующем примере демонстрируется отправка нескольких запросов одновременно с помощью API пакетных запросов. Запросы могут быть представлены в виде списка 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": [{...}]
  }
}

Включить визуализацию

Чтобы получить данные визуализации для запросов журналов с помощью оператора render, выполните следующие действия:

  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
}

Запрос метрик

В следующем примере возвращаются метрики для подписки сетки событий. Универсальный код ресурса (URI) — это URI раздела Сетки событий.

URI ресурса должен быть URI ресурса, для которого запрашиваются метрики. Обычно это формат /subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>.

Чтобы найти URI ресурса, выполните следующие действия:

  1. Перейдите на страницу ресурса в портал Azure.
  2. В колонке Обзор выберите ссылку Представление JSON .
  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)

Обработка ответа на запрос метрик

API запроса метрик возвращает 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.

Примеры запросов журналов

Примеры запросов метрик

Участие

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см. на странице cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Это потребуется сделать только один раз во всех репозиториях с помощью нашего CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.