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

Клиентская библиотека приема Azure Monitor используется для отправки пользовательских журналов в Azure Monitor с помощью API приема журналов.

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

Ресурсы:

• Исходный код
• Пакет (NPM)
• Документация по службе
• Журнал изменений

Начало работы

Предварительные требования

• Подписка Azure
• Конечная точка сбора данных
• Правило сбора данных
• Рабочая область Log Analytics

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

Установите клиентую библиотеку приема Azure Monitor для JS с помощью npm:

npm install @azure/monitor-ingestion

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

Для приема данных требуется клиент, прошедший проверку подлинности. Для проверки подлинности создайте экземпляр класса TokenCredential (см . @azure/identity для DefaultAzureCredential и других TokenCredential реализаций). Передайте его конструктору клиентского класса.

Для проверки подлинности в следующем примере используется DefaultAzureCredential из пакета @azure/identity :

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

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

По умолчанию клиент настроен для использования общедоступного облака Azure. Чтобы вместо этого использовать национальное облако, укажите правильную конечную точку и значение аудитории при создании экземпляра клиента. Пример:

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

Основные понятия

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

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

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

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

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

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

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

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

• CommonSecurityLog
• SecurityEvents
• Syslog
• WindowsEvents

Примеры

• Отправка пользовательских журналов
• Проверка журналов

Вы можете ознакомиться с различными API с помощью примеров.

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

Вы можете создать клиент и вызвать метод клиента Upload . Обратите внимание на ограничения приема данных.

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

Проверка журналов

Вы можете проверить правильность отправки данных с помощью библиотеки @azure/monitor-query . Сначала запустите пример Отправки пользовательских журналов , прежде чем проверять журналы.

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

Отправка больших пакетов журналов

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

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

Получение журналов

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

Устранение неполадок

Дополнительные сведения о диагностике различных сценариев сбоев см. в нашем руководстве по устранению неполадок.

Дальнейшие действия

Дополнительные сведения об Azure Monitor см. в документации по службе Azure Monitor. Подробные примеры использования этой библиотеки см. в каталоге примеров .

Участие

Если вы хотите вносить изменения в эту библиотеку, ознакомьтесь с руководством по внесению изменений, в котором содержатся сведения о создании и тестировании кода.