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

  • [アーティクル]

Azure Monitor インジェスト クライアント ライブラリは、Logs Ingestion API を使用してカスタム ログを Azure Monitor に送信するために使用されます。

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

リソース:

作業の開始

前提条件

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

npm を使用して JS 用 Azure Monitor インジェスト クライアント ライブラリをインストールします。

npm install @azure/monitor-ingestion

クライアントを認証する

データを取り込むには、認証されたクライアントが必要です。 認証するには、TokenCredential クラスのインスタンスを作成します (およびその他TokenCredentialの実装の@azure/ID に関DefaultAzureCredentialするページを参照してください)。 クライアント クラスのコンストラクターに渡します。

認証を行うために、次の例では、@azure/ID パッケージから を使用DefaultAzureCredentialします。

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

主要な概念

データ収集エンドポイント

データ収集エンドポイント (DCE) を使用すると、Azure Monitor のデータ収集エンドポイントのインジェスト設定を一意に構成できます。 この記事 では、データ収集エンドポイントの内容と構造、およびそれらを作成して操作する方法など、データ収集エンドポイントの概要について説明します。

データ収集ルール

データ収集ルール (DCR) は、Azure Monitor によって収集されるデータを定義し、そのデータの送受信方法と場所を指定します。 REST API 呼び出しでは、使用する DCR を指定する必要があります。 1 つの DCE で複数の DCR をサポートできます。そのため、ソース テーブルとターゲット テーブルごとに異なる DCR を指定できます。

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

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

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

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

例

サンプルを使用して、さまざまな 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 };

ログの大規模なバッチのアップロード

の メソッドLogsIngestionClientの 1 回の呼び出しで 1 MB を超えるログをuploadアップロードすると、アップロードは複数の小さなバッチに分割され、それぞれが 1 MB 以下になります。 既定では、これらのバッチは並列でアップロードされ、最大 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 };

ログを取得する

Monitor Ingestion クライアント ライブラリを使用してアップロードされたログは、 Monitor Query クライアント ライブラリを使用して取得できます。

トラブルシューティング

ログ記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、 環境変数を AZURE_LOG_LEVEL に info設定します。 または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

ログを有効にする方法の詳細な手順については、 @azure/logger パッケージのドキュメントを参照してください。

次のステップ

Azure Monitor の詳細については、 Azure Monitor サービスのドキュメントを参照してください。 このライブラリの使用方法の詳細な 例については、 samples ディレクトリを参照してください。

共同作成

このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。

インプレッション数