JS 用の Azure Monitor インジェスト クライアント ライブラリ

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

このライブラリを使用すると、ほぼすべてのソースから、サポートされている組み込みテーブルや、Log Analytics ワークスペースで作成したカスタム テーブルにデータを送信できます。 組み込みテーブルのスキーマをカスタム列で拡張することもできます。

Resources:

• Source code
• Package (NPM)
• Service documentation
• Change log

Getting started

Prerequisites

• An Azure subscription
• データ収集エンドポイント
• データ収集ルール
• Log Analytics ワークスペース

パッケージをインストールする

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 を指定する必要があります。 1 つの DCE で複数の DCR をサポートできるため、ソースとターゲットテーブルごとに異なる DCR を指定できます。

DCR は、入力データの構造とターゲット・テーブルの構造を理解する必要があります。 2 つが一致しない場合は、変換を使用して、ソース データをターゲット テーブルと一致するように変換できます。 また、変換を使用してソース データをフィルター処理し、その他の計算や変換を実行することもできます。

詳細については、「 Azure Monitor のデータ収集ルール」を参照してください。DCR ID を取得する方法については、 このチュートリアルを参照してください。

Log Analytics ワークスペース テーブル

カスタム ログでは、作成した任意のカスタム テーブルと、Log Analytics ワークスペース内の特定の組み込みテーブルにデータを送信できます。 ターゲット テーブルは、データを送信する前に存在している必要があります。 現在、次の組み込みテーブルがサポートされています。

• CommonSecurityLog
• SecurityEvents
• Syslog
• WindowsEvents

Examples

• カスタムログのアップロード
• Verify logs

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

大量のログのアップロード

LogsIngestionClient で upload メソッドを 1 回呼び出すと、アップロードは 1MB 以下のいくつかの小さなバッチに分割されます。 デフォルトでは、これらのバッチは並行してアップロードされ、最大 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.