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

Artigo
11/09/2023

A biblioteca de cliente de Ingestão do Azure Monitor é utilizada para enviar registos personalizados para o Azure Monitor com a API de Ingestão de Registos.

Esta biblioteca permite-lhe enviar dados de praticamente qualquer origem para tabelas incorporadas suportadas ou para tabelas personalizadas que criar na área de trabalho do Log Analytics. Pode até expandir o esquema de tabelas incorporadas com colunas personalizadas.

Recursos:

Introdução

Pré-requisitos

Python 3.7 ou posterior
Uma subscrição do Azure
Uma área de trabalho do Azure Log Analytics
Um Ponto Final de Recolha de Dados
Uma Regra de Recolha de Dados

Instalar o pacote

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

pip install azure-monitor-ingestion

Criar o cliente

É necessário um cliente autenticado para carregar registos para o Azure Monitor. A biblioteca inclui formas síncronas e assíncronas dos clientes. Para autenticar, crie uma instância de uma credencial de token. Utilize essa instância ao criar um LogsIngestionClient. Os exemplos seguintes são utilizados DefaultAzureCredential a partir do pacote azure-identity .

Clientes síncronos

Considere o exemplo seguinte, que cria clientes síncronos para carregar registos:

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 de cliente encontram-se no .aioespaço de nomes -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 clouds não públicas do Azure

Por predefinição, LogsIngestionClient está configurado para ligar à cloud pública do Azure. Para ligar a clouds do Azure não públicas, é necessária alguma configuração adicional. O âmbito adequado para a autenticação tem de ser fornecido com o credential_scopes argumento de palavra-chave. O exemplo seguinte mostra como configurar o cliente para ligar ao Azure US Government:

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

Conceitos-chave

Ponto Final de Recolha de Dados

Os Pontos Finais de Recolha de Dados (DCEs) permitem-lhe configurar de forma exclusiva as definições de ingestão do Azure Monitor. Este artigo fornece uma descrição geral dos pontos finais de recolha de dados, incluindo os respetivos conteúdos e estrutura e como pode criar e trabalhar com os mesmos.

Regra de Recolha de Dados

As regras de recolha de dados (DCR) definem os dados recolhidos pelo Azure Monitor e especificam como e para onde esses dados devem ser enviados ou armazenados. A chamada à API REST tem de especificar um DCR para utilizar. Uma única DCE pode suportar vários DCRs, pelo que pode especificar um DCR diferente para diferentes origens e tabelas de destino.

O DCR tem de compreender a estrutura dos dados de entrada e a estrutura da tabela de destino. Se os dois não corresponderem, pode utilizar uma transformação para converter os dados de origem para corresponderem à tabela de destino. Também pode utilizar a transformação para filtrar dados de origem e efetuar quaisquer outros cálculos ou conversões.

Para obter mais informações, veja Regras de recolha de dados no Azure Monitor e veja este artigo para obter detalhes sobre a estrutura de um DCR. Para obter informações sobre como obter um ID dcr, veja este tutorial.

Tabelas de áreas de trabalho do Log Analytics

Os registos personalizados podem enviar dados para qualquer tabela personalizada que criar e para determinadas tabelas incorporadas na área de trabalho do Log Analytics. A tabela de destino tem de existir antes de poder enviar dados para a mesma. As seguintes tabelas incorporadas são atualmente suportadas:

Obtenção de registos

Os registos que foram carregados com esta biblioteca podem ser consultados com a biblioteca de cliente de Consulta do Azure Monitor .

Exemplos

Carregar registos personalizados
Carregar com o processamento de erros personalizado

Carregar registos personalizados

Este exemplo mostra o carregamento de registos para o 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 o processamento de erros personalizado

Para carregar registos com o processamento de erros personalizado, pode transmitir uma função de chamada de retorno para o on_error parâmetro do upload método . A função de chamada de retorno é chamada para cada erro que ocorre durante o carregamento e deve esperar um argumento que corresponda a um LogsUploadError objeto. Este objeto contém o erro encontrado e a lista de registos que não foi possível carregar.

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

Resolução de problemas

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

Passos seguintes

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

Amostras

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

Exemplos de Ingestão de Registos

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Só terá de o fazer uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, veja a Code of Conduct FAQ (FAQ do Código de Conduta) ou envie um e-mail para opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Partilhar via