Biblioteca de cliente de Ingestão do Azure Monitor para JS

Artigo
06/13/2024

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

Instalar o pacote

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

npm install @azure/monitor-ingestion

Autenticar o cliente

É necessário um cliente autenticado para ingerir dados. Para autenticar, crie uma instância de uma classe TokenCredential (veja @azure/identidade para DefaultAzureCredential e outras TokenCredential implementações). Transmita-o para o construtor da sua classe de cliente.

Para autenticar, o exemplo seguinte utiliza DefaultAzureCredential a partir 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);

Configurar o cliente para a cloud soberana do Azure

Por predefinição, o cliente está configurado para utilizar a Cloud Pública do Azure. Em vez disso, para utilizar uma cloud soberana, forneça o valor de ponto final e de audiência corretos ao instanciar o cliente. Por exemplo:

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, {
  audience: "https://api.loganalytics.azure.cn/.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 detalhes, veja Regras de recolha de dados no Azure Monitor. 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:

Pode familiarizar-se com apIs diferentes com Exemplos.

Carregar registos personalizados

Pode criar um cliente e chamar o método do Upload cliente. Tome nota dos 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 registos

Pode verificar se os seus dados foram carregados corretamente com a biblioteca @azure/monitor-query . Execute primeiro o exemplo Carregar registos personalizados antes de verificar os registos.

// 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 };

Carregar grandes lotes de registos

Ao carregar mais de 1 MB de registos numa única chamada para o upload método em LogsIngestionClient, o carregamento será dividido em vários lotes menores, cada um com mais de 1 MB. Por predefinição, estes lotes serão carregados em paralelo, com um máximo de 5 lotes a serem carregados em simultâneo. Pode ser desejável diminuir a simultaneidade máxima se a utilização da memória for uma preocupação. O número máximo de carregamentos simultâneos pode ser controlado através da 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 };

Obter registos

Os registos carregados com a biblioteca de cliente de Ingestão de Monitores podem ser obtidos com a biblioteca de cliente do Monitor Query.

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. Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar o código.

Impressões

Partilhar via