Клиентская библиотека приема Azure Monitor для JS

2025-07-17

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

Эта библиотека позволяет отправлять данные практически из любого источника в поддерживаемые встроенные таблицы или в пользовательские таблицы, созданные в рабочей области Log Analytics. Вы даже можете расширить схему встроенных таблиц с помощью пользовательских столбцов.

Resources:

Getting started

Prerequisites

Установите пакет

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

npm install @azure/monitor-ingestion

аутентификация клиента;

Для приема данных требуется клиент, прошедший проверку подлинности. To authenticate, create an instance of a TokenCredential class (see @azure/identity for DefaultAzureCredential and other TokenCredential implementations). Передайте его конструктору вашего клиентского класса.

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

Настройка клиента для суверенного облака Azure

По умолчанию клиент настроен на использование общедоступного облака Azure. Чтобы использовать суверенное облако, укажите правильную конечную точку и значение аудитории при создании экземпляра клиента. 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

Конечная точка сбора данных

Конечные точки сбора данных (DCE) позволяют уникально настраивать параметры приема для 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.

Правило сбора данных

Правила сбора данных (DCR) определяют данные, собираемые Azure Monitor, и указывают, как и где эти данные должны отправляться или храниться. В вызове REST API должен быть указан используемый DCR. Один DCE может поддерживать несколько DCR, поэтому вы можете указать другой DCR для разных источников и целевых таблиц.

DCR должен понимать структуру входных данных и структуру целевой таблицы. Если они не совпадают, он может использовать преобразование для преобразования исходных данных в соответствии с целевой таблицей. Преобразование также можно использовать для фильтрации исходных данных и выполнения любых других вычислений или преобразований.

Дополнительные сведения см. в статье Правила сбора данных в Azure Monitor. Сведения о том, как получить идентификатор DCR, см. в этом руководстве.

Таблицы рабочей области Log Analytics

Пользовательские журналы могут отправлять данные в любую настраиваемую таблицу, которую вы создаете, и в определенные встроенные таблицы в рабочей области Log Analytics. Целевая таблица должна существовать, прежде чем можно будет отправить в нее данные. В настоящее время поддерживаются следующие встроенные таблицы:

You can familiarize yourself with different APIs using Samples.

Загрузка пользовательских журналов

Вы можете создать клиента и вызвать метод клиента Upload . 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. Перед проверкой журналов сначала запустите пример отправки пользовательских журналов .

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

Загрузка больших пакетов логов

При загрузке более 1 МБ логов за один вызов upload метода on LogsIngestionClientзагрузка будет разделена на несколько меньших пакетов, каждый размером не более 1 МБ. По умолчанию эти пакеты будут загружаться параллельно, не более 5 пакетов будут загружены одновременно. Может быть желательно уменьшить максимальный параллелизм, если использование памяти является проблемой. Максимальное количество одновременных загрузок можно контролировать с maxConcurrency помощью опции, как показано в следующем примере:

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

Журналы, отправленные с помощью клиентской библиотеки Monitor Ingestion, можно получить с помощью клиентской библиотеки Monitor Query.

Troubleshooting

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

Next steps

Дополнительные сведения об Azure Monitor см. в документации по службе 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.