Azure Monitor-Erfassungsclientbibliothek für JS

Artikel
06/13/2024

Die Azure Monitor-Erfassungsclientbibliothek wird verwendet, um benutzerdefinierte Protokolle mithilfe der Protokollerfassungs-API an Azure Monitor zu senden.

Mit dieser Bibliothek können Sie Daten von praktisch jeder Quelle in unterstützte integrierte Tabellen oder an benutzerdefinierte Tabellen senden, die Sie im Log Analytics-Arbeitsbereich erstellen. Sie können sogar das Schema integrierter Tabellen mit benutzerdefinierten Spalten erweitern.

Ressourcen:

Erste Schritte

Voraussetzungen

Installieren des Pakets

Installieren Sie die Azure Monitor Ingestion-Clientbibliothek für JS mit npm:

npm install @azure/monitor-ingestion

Authentifizieren des Clients

Zum Erfassen von Daten ist ein authentifizierter Client erforderlich. Erstellen Sie zum Authentifizieren eine Instanz einer TokenCredential-Klasse (siehe @azure/Identität für DefaultAzureCredential und andere TokenCredential Implementierungen). Übergeben Sie sie an den Konstruktor Ihrer Clientklasse.

Zum Authentifizieren verwendet DefaultAzureCredential das folgende Beispiel das @azure-/Identitätspaket :

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

Konfigurieren des Clients für Azure Sovereign Cloud

Standardmäßig ist der Client für die Verwendung der öffentlichen Azure-Cloud konfiguriert. Um stattdessen eine souveräne Cloud zu verwenden, geben Sie beim Instanziieren des Clients den richtigen Endpunkt und Zielgruppenwert an. Beispiel:

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

Wichtige Begriffe

Datensammlungsendpunkt

Mit Datensammlungsendpunkten (Data Collection Endpoints, DCEs) können Sie Erfassungseinstellungen für Azure Monitor eindeutig konfigurieren. Dieser Artikel bietet eine Übersicht über Datensammlungsendpunkte, einschließlich ihres Inhalts und ihrer Struktur und wie Sie sie erstellen und damit arbeiten können.

Datensammlungsregel

Datensammlungsregeln (Data Collection Rules, DCR) definieren Daten, die von Azure Monitor gesammelt werden, und geben an, wie und wo diese Daten gesendet oder gespeichert werden sollen. Der REST-API-Aufruf muss eine zu verwendende DCR angeben. Eine einzelne DCR kann mehrere DCRs unterstützen, weshalb Sie eine andere DCR für verschiedene Quellen und Zieltabellen angeben können.

Das DCR muss die Struktur der Eingabedaten und die Struktur der Zieltabelle erkennen. Wenn die beiden nicht übereinstimmen, kann eine Transformation durchgeführt werden, um die Quelldaten so zu konvertieren, dass sie mit der Zieltabelle kompatibel sind. Sie können die Transformation auch verwenden, um Quelldaten zu filtern und andere Berechnungen oder Konvertierungen durchzuführen.

Weitere Informationen finden Sie unter Datensammlungsregeln in Azure Monitor. Informationen zum Abrufen einer DCR-ID finden Sie in diesem Tutorial.

Log Analytics-Arbeitsbereichstabellen

Benutzerdefinierte Protokolle können Daten an jede von Ihnen erstellte benutzerdefinierte Tabelle und an bestimmte integrierte Tabellen in Ihrem Log Analytics-Arbeitsbereich senden. Die Zieltabelle muss existieren, bevor Sie Daten an sie senden können. Die folgenden integrierten Tabellen werden derzeit unterstützt:

Mithilfe von Beispielen können Sie sich mit verschiedenen APIs vertraut machen.

Hochladen benutzerdefinierter Protokolle

Sie können einen Client erstellen und die Methode des Upload Clients aufrufen. Notieren Sie sich die Grenzwerte für die Datenerfassung.

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

Überprüfen von Protokollen

Sie können überprüfen, ob Ihre Daten ordnungsgemäß hochgeladen wurden, indem Sie die bibliothek @azure/monitor-query verwenden. Führen Sie zuerst das Beispiel Benutzerdefinierte Protokolle hochladen aus, bevor Sie die Protokolle überprüfen.

// 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 };

Hochladen großer Protokollbatches

Beim Hochladen von mehr als 1 MB an Protokollen in einem einzigen Aufruf der -Methode auf LogsIngestionClientwird der upload Upload in mehrere kleinere Batches aufgeteilt, die jeweils nicht größer als 1 MB sind. Standardmäßig werden diese Batches parallel hochgeladen, wobei maximal 5 Batches gleichzeitig hochgeladen werden. Es kann wünschenswert sein, die maximale Parallelität zu verringern, wenn die Arbeitsspeicherauslastung ein Problem darstellt. Die maximale Anzahl gleichzeitiger Uploads kann mithilfe der maxConcurrency Option gesteuert werden, wie in diesem Beispiel gezeigt:

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

Abrufen von Protokollen

Protokolle, die mit der Clientbibliothek monitor ingestion hochgeladen werden, können mithilfe der Monitor Query-Clientbibliothek abgerufen werden.

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung.

Nächste Schritte

Weitere Informationen zu Azure Monitor finden Sie in der Dokumentation zum Azure Monitor-Dienst. Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis.

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe

Freigeben über