Bibliothèque de client d’ingestion Azure Monitor pour JS

Article
06/13/2024

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);

Configurer le client pour le cloud souverain Azure

Par défaut, le client est configuré pour utiliser le cloud public Azure. Pour utiliser un cloud souverain à la place, fournissez le point de terminaison et la valeur d’audience appropriés lors de l’instanciation du client. Par exemple :

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

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 :

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.

Dépannage

Pour plus d’informations sur le diagnostic de différents scénarios d’échec, consultez notre guide de résolution des problèmes.

É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.

Impressions

Partager via