Biblioteca de clientes de Ingestão do Azure Monitor para Java – versão 1.1.1

  • 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.

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir uma dependência da versão estável mais recente da biblioteca. No snippet a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-ingestion</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente na BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-ingestion</artifactId>
    <version>1.1.1</version>
</dependency>

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, os exemplos a seguir usam DefaultAzureCredentialBuilder do pacote azure-identity .

Autenticando usando o Azure Active Directory

Você pode autenticar com o Azure Active Directory usando a biblioteca de identidade do Azure. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, inclua o azure-identity pacote:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.1</version>
</dependency>

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET.

Cliente de ingestão de logs síncronos

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildClient();

Cliente de ingestão de logs assíncronos

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionAsyncClient asyncClient = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildAsyncClient();

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 detalhes, consulte Regras de coleta de dados no Azure Monitor. Para obter informações sobre como recuperar uma ID de DCR, consulte este tutorial.

Tabelas do 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

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
client.upload("<data-collection-rule-id>", "<stream-name>", logs);
System.out.println("Logs uploaded successfully");

Carregar logs personalizados com simultaneidade máxima

Se a coleção de logs de entrada for muito grande, o cliente dividirá a entrada em várias solicitações menores. Essas solicitações são enviadas em série, por padrão, mas configurando a simultaneidade máxima no LogsUploadOptions, essas solicitações podem ser enviadas simultaneamente ao serviço, conforme mostrado no exemplo abaixo.

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setMaxConcurrency(3);
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);
System.out.println("Logs uploaded successfully");

Carregar logs personalizados com tratamento de erros

Ao carregar uma grande coleção de logs, o cliente divide a entrada em várias solicitações de serviço menores. O método upload fornece uma opção para lidar com erros de serviço individuais por meio de um manipulador de erros, conforme mostrado no exemplo abaixo. Esse manipulador de erros inclui os detalhes da exceção e a lista de todos os logs que não foram carregados. Se um manipulador de erros não for fornecido, o método de upload gerará uma exceção de agregação que inclui todos os erros de serviço.

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();

LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setLogsUploadErrorConsumer(uploadLogsError -> {
            System.out.println("Error message " + uploadLogsError.getResponseException().getMessage());
            System.out.println("Total logs failed to upload = " + uploadLogsError.getFailedLogs().size());

            // throw the exception here to abort uploading remaining logs
            // throw uploadLogsError.getResponseException();
        });
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);

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

Mais exemplos podem ser encontrados aqui.

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 https://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 que usam 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 contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões