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

The Azure Monitor Ingestion client library is used to send custom logs to Azure Monitor using the Logs Ingestion API.

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é estender o esquema de tabelas internas com colunas personalizadas.

Resources:

Getting started

Prerequisites

Instalar o pacote

Install the Azure Monitor Ingestion client library for JS with npm:

npm install @azure/monitor-ingestion

Autenticar o cliente

Um cliente autenticado é necessário para ingerir dados. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Passe-o para o construtor da classe de cliente.

To authenticate, the following example uses DefaultAzureCredential from the @azure/identity package:

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

const logsIngestionEndpoint = "https://<my-endpoint>.azure.com";

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

Configurar o cliente para a nuvem soberana do Azure

Por padrão, o cliente é configurado para usar a Nuvem Pública do Azure. Para usar uma nuvem soberana, forneça o ponto de extremidade correto e o valor de público-alvo ao instanciar o cliente. For example:

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

const logsIngestionEndpoint = "https://<my-endpoint>.azure.cn";

const credential = new DefaultAzureCredential();
const logsIngestionClient = new LogsIngestionClient(logsIngestionEndpoint, credential, {
  audience: "https://api.loganalytics.azure.cn/.default",
});

Key concepts

Ponto de extremidade da coleta de dados

Os DCEs (Pontos de Extremidade de Coleta de Dados) permitem que você defina exclusivamente as configurações de ingestão para o Azure Monitor. This article provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.

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 um DCR a ser usado. Um único DCE pode dar suporte a vários DCRs, portanto, você pode especificar um DCR diferente para diferentes origens e tabelas de destino.

O DCR deve entender a estrutura dos dados de entrada e a estrutura da tabela de destino. Se os dois não corresponderem, ele poderá usar uma transformação para converter os dados de origem para corresponder à tabela de destino. Você também pode usar a transformação para filtrar dados de origem e realizar 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 do DCR, consulte este tutorial.

Tabelas de espaço de trabalho do Log Analytics

Os logs personalizados podem enviar dados para qualquer tabela personalizada que você criar e para determinadas tabelas internas em seu workspace do Log Analytics. A tabela de destino deve existir para que você possa enviar dados a ela. Atualmente, há suporte para as seguintes tabelas internas:

You can familiarize yourself with different APIs using Samples.

Carregar logs personalizados

Você pode criar um cliente e chamar o método do Upload cliente. Take note of the data ingestion limits.

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

const logsIngestionEndpoint = "https://<my-endpoint>.azure.com";
const ruleId = "data_collection_rule_id";
const streamName = "data_stream_name";

const credential = new DefaultAzureCredential();
const logsIngestionClient = 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 logsIngestionClient.upload(ruleId, streamName, logs);
} catch (e) {
  const 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(`An error occurred: ${e}`);
  }
}

Verify logs

You can verify that your data has been uploaded correctly by using the @azure/monitor-query library. Execute o exemplo Carregar logs personalizados antes de verificar os logs.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient } from "@azure/monitor-query";

const monitorWorkspaceId = "workspace_id";
const tableName = "table_name";

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]),
  );
}

Carregando grandes lotes de logs

Ao fazer upload de mais de 1 MB de logs em uma única chamada para o upload método no LogsIngestionClient, o upload será dividido em vários lotes menores, cada um com no máximo 1 MB. Por padrão, esses lotes serão carregados em paralelo, com um máximo de 5 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 maxConcurrency opção, conforme mostrado neste exemplo:

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

const logsIngestionEndpoint = "https://<my-endpoint>.azure.com";
const ruleId = "data_collection_rule_id";
const streamName = "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);
  }
}

Retrieve logs

Os logs carregados usando a biblioteca de clientes do Monitor Ingestion podem ser recuperados usando a biblioteca de clientes do Monitor Query.

Troubleshooting

For details on diagnosing various failure scenarios, see our troubleshooting guide.

Next steps

Para saber mais sobre o Azure Monitor, consulte a documentação do serviço do Azure Monitor. Please take a look at the samples directory for detailed examples on how to use this library.

Contributing

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

Comentários

Esta página foi útil?

Last updated on 2025-07-17