Клиентская библиотека запросов Azure Monitor для Python — версия 1.2.0
Клиентская библиотека запросов Azure Monitor используется для выполнения запросов только для чтения к двум платформам данных Azure Monitor:
- Журналы — собирает и упорядочивает данные журналов и производительности из отслеживаемых ресурсов. Данные из различных источников, таких как журналы платформы из служб Azure, журналы и данные о производительности из агентов виртуальных машин, а также данные об использовании и производительности из приложений, можно объединить в одну рабочую область Azure Log Analytics. Различные типы данных можно анализировать вместе с помощью язык запросов Kusto.
- Метрики — собирает числовые данные из отслеживаемых ресурсов в базу данных временных рядов. Метрики — это числовые значения, которые собираются через регулярные интервалы и описывают определенный аспект ресурса на определенный момент времени. Метрики являются упрощенными и способны поддерживать сценарии практически в реальном времени, что делает их полезными для оповещения и быстрого обнаружения проблем.
Ресурсы:
- Исходный код
- Пакет (PyPI)
- Пакет (Conda)
- Справочная документация по API
- Документация по службе
- Примеры
- Журнал изменений
Начало работы
Предварительные требования
- Python 3.7 или более поздней версии
- Подписка Azure
- Реализация TokenCredential , например тип учетных данных библиотеки удостоверений Azure.
- Для запроса журналов требуется рабочая область Azure Log Analytics.
- Для запроса метрик требуется ресурс Azure любого типа (учетная запись хранения, Key Vault, Cosmos DB и т. д.).
Установка пакета
Установите клиентную библиотеку запросов 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>']
)
Полный пример можно найти здесь.
Включить статистику
Чтобы получить статистику выполнения запросов журналов, например потребление ЦП и памяти, выполните следующие действия.
- Установите для параметра
include_statistics
значениеTrue
. - Доступ к полю
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, выполните следующие действия:
- Задайте свойству
include_visualization
значениеTrue
. - Доступ к полю
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 ресурса, выполните следующие действия:
- Перейдите на страницу ресурса в портал Azure.
- В колонке Обзор выберите ссылку Представление JSON .
- В результирующем коде 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
объектов типа , granularity
namespace
и 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.
Примеры запросов журналов
- Отправка одного запроса с помощью LogsQueryClient и обработка ответа в виде таблицы (асинхронный пример)
- Отправка одного запроса с помощью LogsQueryClient и обработка ответа в форме "ключ-значение"
- Отправка одного запроса с помощью LogsQueryClient без Pandas
- Отправка одного запроса с помощью LogsQueryClient в нескольких рабочих областях
- Отправка нескольких запросов с помощью LogsQueryClient
- Отправка одного запроса с помощью LogsQueryClient с использованием времени ожидания сервера
Примеры запросов метрик
- Отправка запроса с помощью MetricsQueryClient (асинхронный пример)
- Получение списка пространств имен метрик (асинхронный пример)
- Получение списка определений метрик (асинхронный пример)
Участие
На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см. на странице cla.microsoft.com.
При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Это потребуется сделать только один раз во всех репозиториях с помощью нашего CLA.
В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.
Azure SDK for Python