Biblioteca de clientes de Ingestão do Azure Monitor para Python – versão 1.0.3

  • Artigo

A biblioteca de clientes de Ingestão do Azure Monitor é usada para enviar logs personalizados para o Azure Monitor usando a API de Ingestão de Logs.

Essa biblioteca permite que você envie dados de praticamente qualquer fonte para tabelas internas com suporte ou para tabelas personalizadas criadas no workspace do Log Analytics. Você pode até mesmo estender o esquema de tabelas internas com colunas personalizadas.

Recursos:

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes de Ingestão do Azure Monitor para Python com pip:

pip install azure-monitor-ingestion

Crie o cliente

Um cliente autenticado é necessário para carregar logs no Azure Monitor. A biblioteca inclui formas síncronas e assíncronas dos clientes. Para autenticar, crie uma instância de uma credencial de token. Use essa instância ao criar um LogsIngestionClient. Os exemplos a seguir usam DefaultAzureCredential do pacote azure-identity .

Clientes síncronos

Considere o exemplo a seguir, que cria clientes síncronos para carregar logs:

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 assíncronos

As formas assíncronas das APIs do cliente são encontradas no .aionamespace -sufixo. Por exemplo:

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)

Configurar clientes para nuvens não públicas do Azure

Por padrão, LogsIngestionClient é configurado para se conectar à nuvem pública do Azure. Para se conectar a nuvens não públicas do Azure, algumas configurações adicionais são necessárias. O escopo apropriado para autenticação deve ser fornecido usando o credential_scopes argumento palavra-chave. O exemplo a seguir mostra como configurar o cliente para se conectar ao Azure US Government:

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

Principais conceitos

Ponto de extremidade de coleta de dados

Os DCEs (Pontos de Extremidade de Coleta de Dados) permitem definir exclusivamente as configurações de ingestão para Azure Monitor. Este artigo fornece uma visão geral dos pontos de extremidade de coleta de dados, incluindo seu conteúdo e estrutura e como você pode criar e trabalhar com eles.

Regra de coleta de dados

As DCR (regras de coleta de dados) definem os dados coletados pelo Azure Monitor e especificam como e onde esses dados devem ser enviados ou armazenados. A chamada à API REST deve especificar uma DCR a ser usada. Um único DCE pode dar suporte a várias DCRs, para que você possa especificar uma DCR diferente para fontes diferentes e tabelas de destino.

A DCR deve entender a estrutura dos dados de entrada e a estrutura da tabela de destino. Se as duas não forem correspondentes, ela poderá usar uma transformação para converter os dados de origem a fim de fazer uma correspondência à tabela de destino. Você também pode usar a transformação para filtrar os dados de origem e executar quaisquer outros cálculos ou conversões.

Para obter mais informações, consulte Regras de coleta de dados no Azure Monitor e confira este artigo para obter detalhes sobre a estrutura de um DCR. Para obter informações sobre como recuperar uma ID de DCR, consulte este tutorial.

Tabelas de workspace do Log Analytics

Os logs personalizados podem enviar dados para qualquer tabela personalizada que você criar e para determinadas tabelas internas no workspace do Log Analytics. A tabela de destino deve existir para que você possa enviar dados a ela. As seguintes tabelas internas têm suporte no momento:

Recuperação de logs

Os logs que foram carregados usando essa biblioteca podem ser consultados usando a biblioteca de clientes de Consulta do Azure Monitor .

Exemplos

Carregar logs personalizados

Este exemplo mostra o carregamento de logs no 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}")

Carregar com tratamento de erro personalizado

Para carregar logs com tratamento de erro personalizado, você pode passar uma função de retorno de chamada para o on_error parâmetro do upload método . A função de retorno de chamada é chamada para cada erro que ocorre durante o upload e deve esperar um argumento que corresponda a um LogsUploadError objeto . Esse objeto contém o erro encontrado e a lista de logs que não foram carregados.

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

Solução de problemas

Para obter detalhes sobre como diagnosticar vários cenários de falha, consulte nosso guia de solução de problemas.

Próximas etapas

Para saber mais sobre o Azure Monitor, confira a documentação do serviço do Azure Monitor.

Exemplos

Os exemplos de código a seguir mostram cenários comuns com a biblioteca de clientes de Ingestão do Azure Monitor.

Exemplos de ingestão de logs

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.