Biblioteca cliente de ingesta de Azure Monitor para JS

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

Esta biblioteca permite enviar datos desde prácticamente cualquier origen a tablas integradas compatibles o a tablas personalizadas que cree en el área de trabajo de Log Analytics. Incluso puede ampliar el esquema de las tablas integradas con columnas personalizadas.

Resources:

Getting started

Prerequisites

Instalación del paquete

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

npm install @azure/monitor-ingestion

Autenticación del cliente

Se requiere un cliente autenticado para ingerir datos. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Páselo al constructor de su clase 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);

Configuración del cliente para la nube soberana de Azure

De forma predeterminada, el cliente está configurado para usar la nube pública de Azure. Para usar una nube soberana en su lugar, proporcione el punto de conexión y el valor de audiencia correctos al crear una instancia del 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

Punto de conexión de recopilación de datos

Los puntos de conexión de recopilación de datos (DCE) permiten configurar de forma única las opciones de ingesta para 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.

Regla de recopilación de datos

Las reglas de recopilación de datos (DCR) definen los datos recopilados por Azure Monitor y especifican cómo y dónde se deben enviar o almacenar esos datos. La llamada a la API de REST debe especificar un DCR que se va a utilizar. Un solo DCE puede admitir varias DCR, por lo que puede especificar una DCR diferente para diferentes orígenes y tablas de destino.

El DCR debe comprender la estructura de los datos de entrada y la estructura de la tabla de destino. Si los dos no coinciden, puede usar una transformación para convertir los datos de origen para que coincidan con la tabla de destino. También puede utilizar la transformación para filtrar los datos de origen y realizar cualquier otro cálculo o conversion.

Para obtener más información, consulte Reglas de recopilación de datos en Azure Monitor. Para obtener información sobre cómo recuperar un ID de DCR, consulte este tutorial.

Tablas del área de trabajo de Log Analytics

Los registros personalizados pueden enviar datos a cualquier tabla personalizada que cree y a determinadas tablas integradas en el área de trabajo de Log Analytics. La tabla de destino debe existir antes de poder enviarle datos. Actualmente se admiten las siguientes tablas integradas:

You can familiarize yourself with different APIs using Samples.

Carga de registros personalizados

Puede crear un cliente y llamar al método del 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. Ejecute primero el ejemplo Cargar registros personalizados antes de comprobar los registros.

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

Carga de grandes lotes de registros

Al cargar más de 1 MB de registros en una sola llamada al upload método en LogsIngestionClient, la carga se dividirá en varios lotes más pequeños, cada uno de los cuales no superará 1 MB. De forma predeterminada, estos lotes se cargarán en paralelo, con un máximo de 5 lotes que se cargarán simultáneamente. Puede ser conveniente disminuir la simultaneidad máxima si el uso de memoria es un problema. El número máximo de cargas simultáneas se puede controlar mediante la maxConcurrency opción, como se muestra en este ejemplo:

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

Los registros cargados mediante la biblioteca cliente de ingesta de Monitor se pueden recuperar mediante la biblioteca cliente de consulta de Monitor.

Troubleshooting

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

Next steps

Para más información sobre Azure Monitor, consulte la documentación del servicio 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.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-07-17