Biblioteca cliente de ingesta de Azure Monitor para JS
La biblioteca cliente de ingesta de Azure Monitor se usa para enviar registros personalizados a Azure Monitor mediante la API de ingesta de registros.
Esta biblioteca le permite enviar datos desde prácticamente cualquier origen a tablas integradas admitidas o a tablas personalizadas que cree en el área de trabajo de Log Analytics. Incluso puede extender el esquema de las tablas integradas con columnas personalizadas.
Recursos:
Introducción
Requisitos previos
- Una suscripción de Azure
- Un punto de conexión de recopilación de datos
- Una regla de recopilación de datos
- Un área de trabajo de Log Analytics
Instalar el paquete
Instale la biblioteca cliente de ingesta de Azure Monitor para JS con npm:
npm install @azure/monitor-ingestion
Autenticar el cliente
Se requiere un cliente autenticado para ingerir datos. Para autenticarse, cree una instancia de una clase TokenCredential (consulte @azure/identity para DefaultAzureCredential y otras TokenCredential implementaciones). Páselo al constructor de la clase de cliente.
Para autenticarse, en el ejemplo siguiente se usa DefaultAzureCredential desde el paquete de @azure/identity :
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);
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. Por ejemplo:
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",
});
Conceptos clave
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 los valores de ingesta de Azure Monitor. En este artículo se proporciona información general sobre los puntos de conexión de recopilación de datos, incluidos su contenido y estructura, y cómo puede crearlos y trabajar con ellos.
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 API de REST debe especificar una DCR que se usará. Un único DCE puede admitir varias DCR, por lo que puede especificar una DCR diferente para orígenes y tablas de destino distintos.
La DCR debe comprender la estructura de los datos de entrada y la estructura de la tabla de destino. Si las 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 usar la transformación para filtrar los datos de origen y realizar cualquier otro cálculo o conversión.
Para más información, consulte Reglas de recopilación de datos en Azure Monitor. Para obtener información sobre cómo recuperar un identificador 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 tablas integradas siguientes:
Ejemplos
Puede familiarizarse con diferentes API mediante ejemplos.
Carga de registros personalizados
Puede crear un cliente y llamar al método del Upload cliente. Tome nota de los límites de ingesta de datos.
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 };
Comprobación de registros
Puede comprobar que los datos se han cargado correctamente mediante la biblioteca de @azure/monitor-query . Ejecute primero el ejemplo Cargar registros personalizados antes de comprobar los registros.
// 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 };
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 ellos no mayor que 1 MB. De forma predeterminada, estos lotes se cargarán en paralelo, con un máximo de 5 lotes que se cargan simultáneamente. Puede ser conveniente reducir 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:
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 };
Recuperación de registros
Los registros cargados mediante la biblioteca cliente de ingesta de monitores se pueden recuperar mediante la biblioteca cliente de consulta de supervisión.
Solución de problemas
Para más información sobre cómo diagnosticar varios escenarios de error, consulte nuestra guía de solución de problemas.
Pasos siguientes
Para más información sobre Azure Monitor, consulte la documentación del servicio Azure Monitor. Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.
Contribuciones
Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.
Azure SDK for JavaScript