Klientbibliotek för Azure Monitor-inmatning för JS

2025-07-17

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

Med det här biblioteket kan du skicka data från praktiskt taget vilken källa som helst till inbyggda tabeller som stöds eller till anpassade tabeller som du skapar i Log Analytics-arbetsytan. Du kan till och med utöka schemat för inbyggda tabeller med anpassade kolumner.

Resources:

Getting started

Prerequisites

Installera paketet

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

npm install @azure/monitor-ingestion

Autentisera klienten

En autentiserad klient krävs för att mata in data. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Skicka den till konstruktorn för klientklassen.

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

Konfigurera klienten för Azures nationella moln

Som standard är klienten konfigurerad för att använda det offentliga Azure-molnet. Om du vill använda ett suveränt moln i stället anger du rätt slutpunkt och målgruppsvärde när du instansierar klienten. 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

Slutpunkt för datainsamling

Med datainsamlingsslutpunkter (DCEs) kan du unikt konfigurera inmatningsinställningar för 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.

Regel för datainsamling

Datainsamlingsregler (DCR) definierar data som samlas in av Azure Monitor och anger hur och var dessa data ska skickas eller lagras. REST API-anropet måste ange en DCR som ska användas. En enda domänkontrollant har stöd för flera domänkontrollanter, så du kan ange en annan domänkontrollant för olika källor och måltabeller.

DCR måste förstå strukturen för indata och strukturen för måltabellen. Om de två inte matchar kan den använda en transformering för att konvertera källdata så att de matchar måltabellen. Du kan också använda transformeringen för att filtrera källdata och utföra andra beräkningar eller konverteringar.

Mer information finns i Datainsamlingsregler i Azure Monitor. Information om hur du hämtar ett DCR-ID finns i den här självstudien.

Tabeller för Log Analytics-arbetsyta

Anpassade loggar kan skicka data till alla anpassade tabeller som du skapar och till vissa inbyggda tabeller på Log Analytics-arbetsytan. Måltabellen måste finnas innan du kan skicka data till den. Följande inbyggda tabeller stöds för närvarande:

You can familiarize yourself with different APIs using Samples.

Ladda upp anpassade loggar

Du kan skapa en klient och anropa klientens Upload metod. 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. Kör exemplet Ladda upp anpassade loggar först innan du verifierar loggarna.

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

Ladda upp stora mängder loggar

När du laddar upp mer än 1 MB loggar i ett enda anrop till upload metoden på LogsIngestionClientdelas uppladdningen upp i flera mindre batchar, var och en inte större än 1 MB. Som standard laddas dessa batchar upp parallellt, med högst 5 batchar som laddas upp samtidigt. Det kan vara önskvärt att minska den maximala samtidigheten om minnesanvändningen är ett problem. Det maximala antalet samtidiga uppladdningar kan styras med hjälp av alternativet maxConcurrency , som du ser i det här exemplet:

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

Loggar som laddats upp med hjälp av klientbiblioteket för övervakarinmatning kan hämtas med hjälp av klientbiblioteket för övervakningsfrågor.

Troubleshooting

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

Next steps

Mer information om Azure Monitor finns i dokumentationen för Azure Monitor-tjänsten. 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.

Feedback

Var den här sidan till hjälp?