Delen via

Azure Monitor Ingestion-clientbibliotheek voor JS

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

Met deze bibliotheek kunt u gegevens uit vrijwel elke bron verzenden naar ondersteunde ingebouwde tabellen of naar aangepaste tabellen die u maakt in de Log Analytics-werkruimte. U kunt zelfs het schema van ingebouwde tabellen uitbreiden met aangepaste kolommen.

Resources:

Getting started

Prerequisites

Installeer het pakket

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

npm install @azure/monitor-ingestion

De client verifiëren

Een geverifieerde client is vereist om gegevens op te nemen. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Geef het door aan de constructeur van uw client class.

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

Client configureren voor onafhankelijke Azure-cloud

Standaard is de client geconfigureerd voor het gebruik van de openbare Azure-cloud. Als u in plaats daarvan een onafhankelijke cloud wilt gebruiken, moet u het juiste eindpunt en de juiste doelgroepwaarde opgeven bij het instantiëren van de 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

Eindpunt voor gegevensverzameling

Met eindpunten voor gegevensverzameling (DCE's) kunt u opname-instellingen voor Azure Monitor op unieke wijze configureren. This article provides an overview of data collection endpoints including their contents and structure and how you can create and work with them.

Regel voor gegevensverzameling

Regels voor gegevensverzameling (DCR) definiëren gegevens die worden verzameld door Azure Monitor en geven op hoe en waar die gegevens moeten worden verzonden of opgeslagen. De REST API-aanroep moet een DCR opgeven die moet worden gebruikt. Een enkele DCE kan meerdere DCR's ondersteunen, zodat u een andere DCR kunt opgeven voor verschillende bronnen en doeltabellen.

De DCR moet de structuur van de invoergegevens en de structuur van de doeltabel begrijpen. Als de twee niet overeenkomen, kan een transformatie worden gebruikt om de brongegevens te converteren zodat ze overeenkomen met de doeltabel. U kunt de transformatie ook gebruiken om brongegevens te filteren en andere berekeningen of conversies uit te voeren.

Raadpleeg de regels voor gegevensverzameling in Azure Monitor voor meer informatie. Zie deze zelfstudie voor informatie over het ophalen van een DCR-ID.

Tabellen van Log Analytics-werkruimten

Aangepaste logboeken kunnen gegevens verzenden naar elke aangepaste tabel die u maakt en naar bepaalde ingebouwde tabellen in uw Log Analytics-werkruimte. Voordat u gegevens naar de doeltabel kunt verzenden, moet deze bestaan. De volgende ingebouwde tabellen worden momenteel ondersteund:

Examples

You can familiarize yourself with different APIs using Samples.

Aangepaste logboeken uploaden

U kunt een client maken en de methode van Upload de client aanroepen. 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. Voer eerst het voorbeeld van aangepaste logboeken uploaden uit voordat u de logboeken verifieert.

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

Uploaden van grote hoeveelheden logboeken

Bij het uploaden van meer dan 1 MB aan logboeken in één enkele aanroep naar de upload methode op LogsIngestionClient, wordt de upload opgesplitst in verschillende kleinere batches, elk niet groter dan 1 MB. Standaard worden deze batches parallel geüpload, met een maximum van 5 batches die tegelijkertijd worden geüpload. Het kan wenselijk zijn om de maximale gelijktijdigheid te verlagen als geheugengebruik een probleem is. Het maximum aantal gelijktijdige uploads kan worden bepaald met behulp van de maxConcurrency optie, zoals in dit voorbeeld wordt weergegeven:

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

Logboeken die zijn geüpload met behulp van de clientbibliotheek Opname van monitoren, kunnen worden opgehaald met behulp van de clientbibliotheek Query Monitor.

Troubleshooting

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

Next steps

Zie de documentatie van de Azure Monitor-service voor meer informatie over 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.