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

  • Статья

Клиентская библиотека приема Azure Monitor используется для отправки пользовательских журналов в Azure Monitor с помощью API приема журналов.

Эта библиотека позволяет отправлять данные практически из любого источника в поддерживаемые встроенные таблицы или пользовательские таблицы, созданные в рабочей области Log Analytics. Можно даже расширить схему встроенных таблиц с помощью пользовательских столбцов.

Ресурсы:

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

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

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

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

pip install azure-monitor-ingestion

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

Для отправки журналов в Azure Monitor требуется клиент, прошедший проверку подлинности. Библиотека включает синхронные и асинхронные формы клиентов. Для проверки подлинности создайте экземпляр учетных данных маркера. Используйте этот экземпляр при создании LogsIngestionClient. В следующих примерах используется DefaultAzureCredential пакет azure-identity .

Синхронные клиенты

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

import os
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

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

Асинхронные формы клиентских API находятся в пространстве имен с суффиксами .aio. Пример:

import os
from azure.identity.aio import DefaultAzureCredential
from azure.monitor.ingestion.aio import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

Настройка клиентов для облаков Azure, не являющихся общедоступными

По умолчанию LogsIngestionClient настроено подключение к общедоступному облаку Azure. Для подключения к облакам Azure, не являющихся общедоступными, требуется дополнительная настройка. Соответствующие область для проверки подлинности должны быть предоставлены с помощью аргумента credential_scopes ключевое слово. В следующем примере показано, как настроить клиент для подключения к Azure для государственных организаций США:

logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"])

Основные понятия

Конечная точка сбора данных

Конечные точки сбора данных (DCE) позволяют уникальным образом настроить параметры приема данных для Azure Monitor. В этой статье представлен обзор конечных точек сбора данных, включая их содержимое и структуру, а также способы их создания и работы с ними.

Правило сбора данных

Правила сбора данных (DCR) определяют данные, собираемые Azure Monitor, и указывают, как и где эти данные должны отправляться или храниться. В вызове REST API должно быть указано DCR для использования. Один DCE может поддерживать несколько DCR, поэтому можно указать разные DCR для разных источников и целевых таблиц.

DCR должно понимать структуру входных данных и структуру целевой таблицы. Если эти две структуры не совпадают, можно использовать преобразование исходных данных в соответствии с целевой таблицей. Можно также использовать преобразование для фильтрации исходных данных и выполнения других вычислений или преобразований.

Дополнительные сведения см . в статье Правила сбора данных в Azure Monitor и в этой статье , чтобы узнать больше о структуре DCR. Сведения о том, как получить идентификатор DCR, см. в этом руководстве.

Таблицы рабочей области Log Analytics

Настраиваемые журналы могут отсылать данные в любую настраиваемую таблицу, созданную вами, и в определенные встроенные таблицы в рабочей области Log Analytics. Целевая таблица должна существовать, прежде чем можно будет отправить в нее данные. В настоящее время поддерживаются приведенные ниже встроенные таблицы.

Получение журналов

Журналы, отправленные с помощью этой библиотеки, можно запрашивать с помощью клиентской библиотеки запросов Azure Monitor .

Примеры

Отправка пользовательских журналов

В этом примере показана отправка журналов в Azure Monitor.

import os

from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()

client = LogsIngestionClient(endpoint=endpoint, credential=credential, logging_enable=True)

rule_id = os.environ['LOGS_DCR_RULE_ID']
body = [
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer1",
        "AdditionalContext": "context-2"
      },
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer2",
        "AdditionalContext": "context"
      }
    ]

try:
    client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body)
except HttpResponseError as e:
    print(f"Upload failed: {e}")

Отправка с пользовательской обработкой ошибок

Чтобы отправить журналы с пользовательской обработкой ошибок, можно передать функцию обратного upload вызова в on_error параметр метода . Функция обратного вызова вызывается для каждой ошибки, возникающей во время отправки, и она должна ожидать один аргумент, соответствующий объекту LogsUploadError . Этот объект содержит обнаруженную ошибку и список журналов, которые не удалось отправить.

# Example 1: Collect all logs that failed to upload.
failed_logs = []
def on_error(error):
    print("Log chunk failed to upload with error: ", error.error)
    failed_logs.extend(error.failed_logs)

# Example 2: Ignore all errors.
def on_error_pass(error):
    pass

client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body, on_error=on_error)

Устранение неполадок

Дополнительные сведения о диагностике различных сценариев сбоя см. в нашем руководстве по устранению неполадок.

Дальнейшие действия

Дополнительные сведения об Azure Monitor см. в документации по службе Azure Monitor.

Примеры

В следующих примерах кода показаны распространенные сценарии с клиентской библиотекой приема Azure Monitor.

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

Участие

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

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

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