Biblioteca de clientes de ingestão do Azure Monitor para JS

Artigo
04/05/2023

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

Uma assinatura do Azure
Um ponto de extremidade de coleta de dados
Uma regra de coleta de dados
Um workspace do Log Analytics

Instalar o pacote

Instale a biblioteca de clientes de Ingestão do Azure Monitor para JS com npm:

npm install @azure/monitor-ingestion

Autenticar o cliente

Um cliente autenticado é necessário para ingerir dados. Para autenticar, crie uma instância de uma classe TokenCredential (consulte @azure/identity para DefaultAzureCredential e outras TokenCredential implementações). Passe-o para o construtor da classe de cliente.

Para autenticar, o exemplo a seguir usa DefaultAzureCredential do pacote de @azure/identidade :

import { DefaultAzureCredential } from "@azure/identity";
import { LogsIngestionClient } from "@azure/monitor-ingestion";

import * as dotenv from "dotenv";
dotenv.config();

const logsIngestionEndpoint = process.env.LOGS_INGESTION_ENDPOINT || "logs_ingestion_endpoint";

const credential = new DefaultAzureCredential();
const logsIngestionClient = new LogsIngestionClient(logsIngestionEndpoint, credential);

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:

Você pode se familiarizar com APIs diferentes usando Exemplos.

Carregar logs personalizados

Você pode criar um cliente e chamar o método do Upload cliente. Anote os limites de ingestão de dados.

const { isAggregateLogsUploadError, DefaultAzureCredential } = require("@azure/identity");
const { LogsIngestionClient } = require("@azure/monitor-ingestion");

require("dotenv").config();

async function main() {
  const logsIngestionEndpoint = process.env.LOGS_INGESTION_ENDPOINT || "logs_ingestion_endpoint";
  const ruleId = process.env.DATA_COLLECTION_RULE_ID || "data_collection_rule_id";
  const streamName = process.env.STREAM_NAME || "data_stream_name";
  const credential = new DefaultAzureCredential();
  const client = new LogsIngestionClient(logsIngestionEndpoint, credential);
  const logs = [
    {
      Time: "2021-12-08T23:51:14.1104269Z",
      Computer: "Computer1",
      AdditionalContext: "context-2",
    },
    {
      Time: "2021-12-08T23:51:14.1104269Z",
      Computer: "Computer2",
      AdditionalContext: "context",
    },
  ];
  try{
    await client.upload(ruleId, streamName, logs);
  }
  catch(e){
    let aggregateErrors = isAggregateLogsUploadError(e) ? e.errors : [];
    if (aggregateErrors.length > 0) {
      console.log("Some logs have failed to complete ingestion");
      for (const error of aggregateErrors) {
        console.log(`Error - ${JSON.stringify(error.cause)}`);
        console.log(`Log - ${JSON.stringify(error.failedLogs)}`);
      }
    } else {
      console.log(e);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
  process.exit(1);
});

module.exports = { main };

Verificar logs

Você pode verificar se os dados foram carregados corretamente usando a biblioteca @azure/monitor-query . Execute o exemplo Carregar logs personalizados primeiro antes de verificar os logs.

// Copyright (c) Microsoft Corporation.
// Licensed under the MIT license.

/**
 * @summary Demonstrates how to run query against a Log Analytics workspace to verify if the logs were uploaded
 */

const { DefaultAzureCredential } = require("@azure/identity");
const { LogsQueryClient } = require("@azure/monitor-query");

const monitorWorkspaceId = process.env.MONITOR_WORKSPACE_ID || "workspace_id";
const tableName = process.env.TABLE_NAME || "table_name";
require("dotenv").config();

async function main() {
  const credential = new DefaultAzureCredential();
  const logsQueryClient = new LogsQueryClient(credential);
  const queriesBatch = [
    {
      workspaceId: monitorWorkspaceId,
      query: tableName + " | count;",
      timespan: { duration: "P1D" },
    },
  ];

  const result = await logsQueryClient.queryBatch(queriesBatch);
  if (result[0].status === "Success") {
    console.log("Table entry count: ", JSON.stringify(result[0].tables));
  } else {
    console.log(
      `Some error encountered while retrieving the count. Status = ${result[0].status}`,
      JSON.stringify(result[0])
    );
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
  process.exit(1);
});

module.exports = { main };

Carregando grandes lotes de logs

Ao carregar mais de 1 MB de logs em uma única chamada para o upload método em LogsIngestionClient, o upload será dividido em vários lotes menores, cada um não maior que 1 MB. Por padrão, esses lotes serão carregados em paralelo, com um máximo de cinco lotes sendo carregados simultaneamente. Pode ser desejável diminuir a simultaneidade máxima se o uso de memória for uma preocupação. O número máximo de uploads simultâneos pode ser controlado usando a opção maxConcurrency , conforme mostrado neste exemplo:

const { DefaultAzureCredential } = require("@azure/identity");
const { isAggregateLogsUploadError, LogsIngestionClient } = require("@azure/monitor-ingestion");

require("dotenv").config();

async function main() {
  const logsIngestionEndpoint = process.env.LOGS_INGESTION_ENDPOINT || "logs_ingestion_endpoint";
  const ruleId = process.env.DATA_COLLECTION_RULE_ID || "data_collection_rule_id";
  const streamName = process.env.STREAM_NAME || "data_stream_name";
  const credential = new DefaultAzureCredential();
  const client = new LogsIngestionClient(logsIngestionEndpoint, credential);

  // Constructing a large number of logs to ensure batching takes place
  const logs = [];
  for (let i = 0; i < 100000; ++i) {
    logs.push({
      Time: "2021-12-08T23:51:14.1104269Z",
      Computer: "Computer1",
      AdditionalContext: `context-${i}`,
    });
  }

  try{
    // Set the maximum concurrency to 1 to prevent concurrent requests entirely
    await client.upload(ruleId, streamName, logs, { maxConcurrency: 1 });
  }
  catch(e){
    let aggregateErrors = isAggregateLogsUploadError(e) ? e.errors : [];
    if (aggregateErrors.length > 0) {
      console.log("Some logs have failed to complete ingestion");
      for (const error of aggregateErrors) {
        console.log(`Error - ${JSON.stringify(error.cause)}`);
        console.log(`Log - ${JSON.stringify(error.failedLogs)}`);
      }
    } else {
      console.log(e);
    }
  }
}
main().catch((err) => {
  console.error("The sample encountered an error:", err);
  process.exit(1);
});

module.exports = { main };

Recuperar logs

Os logs carregados usando a biblioteca de clientes de Ingestão de Monitor podem ser recuperados usando a biblioteca de clientes do Monitor Query.

Solução de problemas

Log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de AZURE_LOG_LEVEL ambiente como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obter instruções detalhadas sobre como habilitar logs, consulte os documentos do pacote de @azure/agente.

Próximas etapas

Para saber mais sobre o Azure Monitor, confira a documentação do serviço Azure Monitor. Dê uma olhada no diretório de exemplos para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões