Freigeben über

Azure Monitor-Erfassungsclientbibliothek für JS

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

Mit dieser Bibliothek können Sie Daten aus praktisch jeder Quelle an 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.

Resources:

Getting started

Prerequisites

Installiere das Paket

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

npm install @azure/monitor-ingestion

Authentifizieren des Clients

Zum Erfassen von Daten ist ein authentifizierter Client erforderlich. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Übergeben Sie sie an den Konstruktor Ihrer Clientklasse.

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

Konfigurieren des Clients für die souveräne Azure-Cloud

Standardmäßig ist der Client für die Verwendung der Azure Public Cloud konfiguriert. Wenn Sie stattdessen eine Sovereign Cloud verwenden möchten, geben Sie beim Instanziieren des Clients den richtigen Endpunkt- und Zielgruppenwert an. 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

Datensammlungsendpunkt

Mit Datensammlungsendpunkten (Data Collection Endpoints, DCEs) können Sie Erfassungseinstellungen für Azure Monitor eindeutig konfigurieren. This article provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.

Regel für die Datenerfassung

Datensammlungsregeln (Data Collection Rules, DCR) definieren die von Azure Monitor gesammelten Daten und geben an, wie und wo diese Daten gesendet oder gespeichert werden sollen. Der REST-API-Aufruf muss einen zu verwendenden DCR angeben. Ein einzelner DCE kann mehrere DCRs unterstützen, sodass Sie einen anderen DCR für verschiedene Quell- und Zieltabellen angeben können.

Der DCR muss die Struktur der Eingabedaten und die Struktur der Zieltabelle verstehen. Wenn die beiden nicht übereinstimmen, kann eine Transformation verwendet werden, um die Quelldaten so zu konvertieren, dass sie mit der Zieltabelle übereinstimmen. 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 benutzerdefinierte Tabelle senden, die Sie erstellen, und an bestimmte integrierte Tabellen in Ihrem Log Analytics-Arbeitsbereich. Die Zieltabelle muss existieren, bevor Sie Daten an sie senden können. Die folgenden integrierten Tabellen werden derzeit unterstützt:

Examples

You can familiarize yourself with different APIs using Samples.

Hochladen von benutzerdefinierten Protokollen

Sie können einen Client erstellen und die Upload Methode des Clients aufrufen. 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. Führen Sie zuerst das Beispiel zum Hochladen benutzerdefinierter Protokolle aus, bevor Sie die Protokolle überprüfen.

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

Hochladen großer Stapel von Protokollen

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

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

Protokolle, die mit der Monitor Ingestion-Clientbibliothek hochgeladen wurden, können mit der Monitor Query-Clientbibliothek abgerufen werden.

Troubleshooting

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

Next steps

Weitere Informationen zu Azure Monitor finden Sie in der Dokumentation zum Azure Monitor-Dienst. 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