Partager via

Bibliothèque cliente d’ingestion Azure Monitor pour JS

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

Cette bibliothèque vous permet d’envoyer des données à partir de pratiquement n’importe quelle source à des tables intégrées prises en charge ou à 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.

Resources:

Getting started

Prerequisites

Installer le package

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

npm install @azure/monitor-ingestion

Authentifier le client

Un client authentifié est requis pour ingérer des données. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Passez-le au constructeur de votre classe 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);

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 corrects lors de l’instanciation du client. 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

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. This article provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.

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 d’API REST doit spécifier un DCR à utiliser. Un seul DCE peut prendre en charge plusieurs DCR, de sorte que vous pouvez spécifier un DCR différent pour différentes sources et tables cibles.

Le DCR doit comprendre la structure des données d’entrée et la structure de la table cible. Si les deux ne correspondent pas, il peut utiliser une transformation pour convertir les données sources afin qu’elles correspondent à la table cible. Vous pouvez également utiliser la transformation pour filtrer les données sources et effectuer d’autres calculs ou 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 de l’espace de travail Log Analytics

Les journaux personnalisés peuvent envoyer des données à n’importe quelle table personnalisée que vous créez 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 suivantes sont actuellement prises en charge :

Examples

You can familiarize yourself with different APIs using Samples.

Charger des journaux personnalisés

Vous pouvez créer un client et appeler la méthode du Upload client. 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. Exécutez d’abord l’exemple Charger des journaux personnalisés avant de vérifier les journaux.

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

Chargement de gros lots de journaux

Lors du chargement de plus de 1 Mo de journaux en un seul appel à la upload méthode le LogsIngestionClient, le chargement sera divisé en plusieurs lots plus petits, chacun ne dépassant pas 1 Mo. Par défaut, ces lots seront téléchargés en parallèle, avec un maximum de 5 lots téléchargés simultanément. Il peut être souhaitable de réduire la simultanéité maximale si l’utilisation de la mémoire est un problème. Le nombre maximal de téléchargements simultanés peut être contrôlé à l’aide de l’option maxConcurrency , comme indiqué dans cet exemple :

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

Les journaux téléchargés à l’aide de la bibliothèque cliente Monitor Ingestion peuvent être récupérés à l’aide de la bibliothèque cliente Monitor Query.

Troubleshooting

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

Next steps

Pour en savoir plus sur Azure Monitor, consultez la documentation du service 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.

  • Last updated on