Compartir a través de

Biblioteca cliente de ingesta de Azure Monitor para Python: versión 1.0.3

  • Artículo

La biblioteca cliente de ingesta de Azure Monitor se usa para enviar registros personalizados a Azure Monitor mediante la API de ingesta de registros.

Esta biblioteca permite enviar datos desde prácticamente cualquier origen a tablas integradas compatibles o a tablas personalizadas que cree en el área de trabajo de Log Analytics. Incluso puede extender el esquema de las tablas integradas con columnas personalizadas.

Recursos:

Introducción

Requisitos previos

Instalar el paquete

Instale la biblioteca cliente de ingesta de Azure Monitor para Python con pip:

pip install azure-monitor-ingestion

Creación del cliente

Se requiere un cliente autenticado para cargar registros en Azure Monitor. La biblioteca incluye formas sincrónicas y asincrónicas de los clientes. Para autenticarse, cree una instancia de una credencial de token. Use esa instancia al crear un LogsIngestionClient. En los ejemplos siguientes se usa DefaultAzureCredential el paquete azure-identity .

Clientes sincrónicos

Considere el ejemplo siguiente, que crea clientes sincrónicos para cargar registros:

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)

Clientes asincrónicos

Las formas asincrónicas de las API de cliente se encuentran en el .aioespacio de nombres -sufijo. Por ejemplo:

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)

Configuración de clientes para nubes de Azure no públicas

De forma predeterminada, LogsIngestionClient está configurado para conectarse a la nube pública de Azure. Para conectarse a nubes de Azure no públicas, se requiere alguna configuración adicional. Se debe proporcionar el ámbito adecuado para la autenticación mediante el argumento de palabra credential_scopes clave . En el ejemplo siguiente se muestra cómo configurar el cliente para conectarse a Azure US Government:

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

Conceptos clave

Punto de conexión de recopilación de datos

Los puntos de conexión de recopilación de datos (DCE) permiten configurar de forma única los valores de ingesta de Azure Monitor. En este artículo se proporciona información general sobre los puntos de conexión de recopilación de datos, incluidos su contenido y su estructura, y cómo puede crearlos y trabajar con ellos.

Regla de recopilación de datos

Las reglas de recopilación de datos (DCR) definen los datos recopilados por Azure Monitor y especifican cómo y dónde se deben enviar o almacenar esos datos. La llamada API de REST debe especificar una DCR que se usará. Un único DCE puede admitir varias DCR, por lo que puede especificar una DCR diferente para orígenes y tablas de destino distintos.

La DCR debe comprender la estructura de los datos de entrada y la estructura de la tabla de destino. Si las dos no coinciden, puede usar una transformación para convertir los datos de origen para que coincidan con la tabla de destino. También puede usar la transformación para filtrar los datos de origen y realizar cualquier otro cálculo o conversión.

Para más información, consulte Reglas de recopilación de datos en Azure Monitor y consulte este artículo para obtener más información sobre la estructura de un DCR. Para obtener información sobre cómo recuperar un identificador de DCR, consulte este tutorial.

Tablas del área de trabajo de Log Analytics

Los registros personalizados pueden enviar datos a cualquier tabla personalizada que cree y a determinadas tablas integradas en el área de trabajo de Log Analytics. La tabla de destino debe existir antes de poder enviarle datos. Actualmente se admiten las tablas integradas siguientes:

Recuperación de registros

Los registros que se cargaron mediante esta biblioteca se pueden consultar mediante la biblioteca cliente de consultas de Azure Monitor .

Ejemplos

Carga de registros personalizados

En este ejemplo se muestra cómo cargar registros en 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}")

Carga con control de errores personalizado

Para cargar registros con control de errores personalizado, puede pasar una función de devolución de llamada al on_error parámetro del upload método . Se llama a la función de devolución de llamada para cada error que se produce durante la carga y debe esperar un argumento que corresponda a un LogsUploadError objeto. Este objeto contiene el error encontrado y la lista de registros que no se pudieron cargar.

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

Solución de problemas

Para más información sobre cómo diagnosticar varios escenarios de error, consulte nuestra guía de solución de problemas.

Pasos siguientes

Para más información sobre Azure Monitor, consulte la documentación del servicio Azure Monitor.

Ejemplos

Los ejemplos de código siguientes muestran escenarios comunes con la biblioteca cliente de ingesta de Azure Monitor.

Ejemplos de ingesta de registros

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo tendrá que hacerlo una vez en todos los repositorios mediante nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.