JS용 Azure Monitor 수집 클라이언트 라이브러리
Azure Monitor 수집 클라이언트 라이브러리는 로그 수집 API를 사용하여 Azure Monitor에 사용자 지정 로그를 보내는 데 사용됩니다.
이 라이브러리를 사용하면 거의 모든 원본에서 지원되는 기본 제공 테이블 또는 Log Analytics 작업 영역에서 만든 사용자 지정 테이블로 데이터를 보낼 수 있습니다. 사용자 지정 열을 사용하여 기본 제공 테이블의 스키마를 확장할 수도 있습니다.
리소스:
시작
필수 구성 요소
패키지 설치
npm을 사용하여 JS용 Azure Monitor 수집 클라이언트 라이브러리를 설치합니다.
npm install @azure/monitor-ingestion
클라이언트 인증
데이터를 수집하려면 인증된 클라이언트가 필요합니다. 인증하려면 TokenCredential 클래스의 인스턴스를 만듭니다(및 기타 TokenCredential 구현에 대한 DefaultAzureCredential@azure/ID 참조). 클라이언트 클래스의 생성자에 전달합니다.
인증하기 위해 다음 예제에서는 @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을 지정해야 합니다. 단일 DCE는 여러 DCR을 지원할 수 있으므로 다른 원본 및 대상 테이블에 대해 다른 DCR을 지정할 수 있습니다.
DCR은 입력 데이터의 구조와 대상 테이블의 구조를 이해해야 합니다. 두 구조가 일치하지 않으면 변환 을 사용하여 원본 데이터를 대상 테이블과 일치하도록 변환할 수 있습니다. 변환을 사용하여 원본 데이터를 필터링하고 다른 계산 또는 변환을 수행할 수도 있습니다.
자세한 내용은 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에 대한 단일 호출 upload 에서 1MB 이상의 로그를 업로드하는 경우 업로드는 각각 1MB 이하의 여러 작은 일괄 처리로 분할됩니다. 기본적으로 이러한 일괄 처리는 병렬로 업로드되며 최대 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 서비스 설명서를 참조하세요. 이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.
참여
이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.
Azure SDK for JavaScript