Bibliothèque de client d’ingestion Azure Monitor pour JS
La bibliothèque cliente d’ingestion Azure Monitor est utilisée pour envoyer des journaux personnalisés à Azure Monitor à l’aide de l’API Ingestion des journaux.
Cette bibliothèque vous permet d’envoyer des données à partir de pratiquement n’importe quelle source vers des tables intégrées prises en charge ou vers des tables personnalisées que vous créez dans l’espace de travail Log Analytics. Vous pouvez même étendre le schéma des tables intégrées avec des colonnes personnalisées.
Ressources :
Prise en main
Prérequis
- Un abonnement Azure
- Point de terminaison de collecte de données
- Une règle de collecte de données
- Un espace de travail Log Analytics
Installer le package
Installez la bibliothèque de client d’ingestion Azure Monitor pour JS avec npm :
npm install @azure/monitor-ingestion
Authentifier le client
Un client authentifié est nécessaire pour ingérer des données. Pour vous authentifier, créez une instance d’une classe TokenCredential (consultez @azure/identity pour DefaultAzureCredential et d’autres TokenCredential implémentations). Passez-le au constructeur de votre classe cliente.
Pour l’authentification, l’exemple suivant utilise DefaultAzureCredential à partir du package @azure/identité :
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);
Concepts clés
Point de terminaison de collecte de données
Les points de terminaison de collecte de données (DCE) vous permettent de configurer de manière unique les paramètres d’ingestion pour Azure Monitor. Cet article fournit une vue d’ensemble des points de terminaison de collecte de données, y compris leur contenu et leur structure, ainsi que la façon dont vous pouvez les créer et les utiliser.
Règle de collecte de données
Les règles de collecte de données (DCR) définissent les données collectées par Azure Monitor et spécifient comment et où ces données doivent être envoyées ou stockées. L’appel de l’API REST doit spécifier une règle de collecte de données à utiliser. Un seul point de terminaison de collecte de données peut prendre en charge plusieurs règles de collecte de données. Vous pouvez donc spécifier une règle de collecte de données différente pour chaque source et chaque table cible.
La règle de collecte de données doit comprendre la structure des données d’entrée et celle de la table cible. Si les deux ne correspondent pas, elle peut utiliser une transformation pour convertir les données sources en fonction de la table cible. Vous pouvez également utiliser la transformation pour filtrer les données sources et effectuer d’autres calculs et conversions.
Pour plus d’informations, consultez Règles de collecte de données dans Azure Monitor. Pour plus d’informations sur la récupération d’un ID DCR, consultez ce tutoriel.
Tables d’espace de travail Log Analytics
Les journaux personnalisés peuvent envoyer des données à n’importe quelle table personnalisée créée par vos soins et à certaines tables intégrées de votre espace de travail Log Analytics. La table cible doit déjà exister pour que vous puissiez lui envoyer des données. Les tables intégrées actuellement prises en charge sont les suivantes :
Exemples
Vous pouvez vous familiariser avec différentes API à l’aide d’exemples.
Charger des journaux personnalisés
Vous pouvez créer un client et appeler la méthode du Upload client. Notez les limites d’ingestion des données.
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 };
Vérifier les journaux
Vous pouvez vérifier que vos données ont été chargées correctement à l’aide de la bibliothèque @azure/monitor-query . Exécutez d’abord l’exemple Charger les journaux personnalisés avant de vérifier les journaux.
// 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 };
Chargement de grands lots de journaux
Lors du chargement de plus de 1 Mo de journaux dans un seul appel à la upload méthode sur LogsIngestionClient, le chargement est fractionné en plusieurs lots plus petits, chacun ne dépassant pas 1 Mo. Par défaut, ces lots sont chargés en parallèle, avec un maximum de 5 lots chargés simultanément. Il peut être souhaitable de diminuer la concurrence maximale si l’utilisation de la mémoire est un problème. Le nombre maximal de chargements simultanés peut être contrôlé à l’aide de l’option maxConcurrency , comme indiqué dans cet exemple :
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 };
Récupérer les journaux
Les journaux chargés à l’aide de la bibliothèque cliente d’ingestion du moniteur peuvent être récupérés à l’aide de la bibliothèque cliente de requête de surveillance.
Résolution des problèmes
Journalisation
L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement sur AZURE_LOG_LEVELinfo. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :
import { setLogLevel } from "@azure/logger";
setLogLevel("info");
Pour obtenir des instructions détaillées sur l’activation des journaux, consultez la documentation sur le package @azure/enregistreur d’événements.
Étapes suivantes
Pour en savoir plus sur Azure Monitor, consultez la documentation du service Azure Monitor. Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.
Contribution
Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.
Azure SDK for JavaScript
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour