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);
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 を指定する必要があります。 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 クライアント ライブラリを使用して取得できます。
トラブルシューティング
さまざまな障害シナリオの診断の詳細については、 トラブルシューティング ガイドを参照してください。
次の手順
Azure Monitor の詳細については、 Azure Monitor サービスのドキュメントを参照してください。 このライブラリの使用方法の詳細な 例については、 samples ディレクトリを参照してください。
共同作成
このライブラリに投稿する場合、コードをビルドしてテストする方法の詳細については、投稿ガイドを参照してください。
Azure SDK for JavaScript