JavaScript용 Azure Monitor 쿼리 로그 클라이언트 라이브러리 - 버전 1.0.0

Azure Monitor 쿼리 로그 클라이언트 라이브러리는 Azure Monitor의 로그 데이터 플랫폼에 대해 읽기 전용 쿼리를 실행하는 데 사용됩니다.

• 로그 - 모니터링되는 리소스에서 로그 및 성능 데이터를 수집하고 구성합니다. Azure 서비스의 플랫폼 로그, 가상 머신 에이전트의 로그 및 성능 데이터, 앱의 사용량 및 성능 데이터와 같은 다양한 원본의 데이터를 단일 Azure Log Analytics 작업 영역으로 통합할 수 있습니다. Kusto 쿼리 언어를 사용하여 다양한 데이터 형식을 함께 분석할 수 있습니다.

권고⚠에서 @azure/monitor-query 마이그레이션 ️

원래 @azure/monitor-query 패키지에서 라이브러리로 @azure/monitor-query-logs 애플리케이션 코드를 업데이트하는 방법에 대한 자세한 지침은 마이그레이션 가이드를 확인하세요.

리소스:

• 소스 코드
• 패키지(npm)
• API 참조 설명서
• 서비스 문서
• 견본
• 변경 기록

시작하기

지원되는 환경

• Node.js의 LTS 버전
• Safari, Chrome, Microsoft Edge 및 Firefox의 최신 버전

자세한 내용은 지원 정책을 참조하세요.

필수 조건

• Azure 서비스 구독
• TokenCredential 구현(예: Azure Identity 라이브러리 자격 증명 형식).
• 로그를 쿼리하려면 다음 중 하나가 필요합니다.
  • Azure Log Analytics 작업 영역
  • 모든 종류의 Azure 리소스(스토리지 계정, Key Vault, Cosmos DB 등)

패키지 설치

npm을 사용하여 JavaScript용 Azure Monitor 쿼리 클라이언트 라이브러리를 설치합니다.

npm install --save @azure/monitor-query-logs

클라이언트 만들기

로그를 쿼리하려면 인증된 클라이언트가 필요합니다. 인증을 위해 다음 예제에서는 @azure/identity 패키지의 DefaultAzureCredential을 사용합니다.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient } from "@azure/monitor-query-logs";

const credential = new DefaultAzureCredential();

// Create a LogsQueryClient
const logsQueryClient = new LogsQueryClient(credential);

Azure 소버린 클라우드에 대한 클라이언트 구성

기본적으로 라이브러리의 클라이언트는 Azure 퍼블릭 클라우드를 사용하도록 구성됩니다. 대신 소버린 클라우드를 사용하려면 클라이언트를 인스턴스화할 때 올바른 엔드포인트 및 대상 그룹 값을 제공합니다. 다음은 그 예입니다.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient } from "@azure/monitor-query-logs";

const credential = new DefaultAzureCredential();

// Create a LogsQueryClient
const logsQueryClient: LogsQueryClient = new LogsQueryClient(credential, {
  endpoint: "https://api.loganalytics.azure.cn/v1",
  audience: "https://api.loganalytics.azure.cn/.default",
});

쿼리 실행

로그 쿼리의 예는 예제 섹션을 참조하세요.

주요 개념

쿼리 속도 제한 및 제한을 기록합니다.

Log Analytics 서비스는 요청 속도가 너무 높을 때 제한을 적용합니다. 반환되는 최대 행 수와 같은 제한은 Kusto 쿼리에도 적용됩니다. 자세한 내용은 쿼리 API를 참조하세요.

예시

• 로그 쿼리
  • 작업 영역 중심 로그 쿼리
  • 리소스 중심 로그 쿼리
  • 로그 쿼리 응답 처리
• Batch 로그 쿼리
  • 로그 일괄 처리 쿼리 응답 처리
• 고급 로그 쿼리 시나리오
  • 로그 쿼리 시간 초과 설정
  • 여러 작업 영역 쿼리
  • 통계 포함
  • 시각화 포함

로그 쿼리

LogsQueryClient Kusto 쿼리 언어를 사용하여 Log Analytics 작업 영역을 쿼리하는 데 사용할 수 있습니다. ISO timespan.duration 8601 기간 형식의 문자열로 지정할 수 있습니다. 일반적으로 사용되는 일부 ISO 8601 기간에 제공된 상수를 사용할 Durations 수 있습니다.

Log Analytics 작업 영역 ID 또는 Azure 리소스 ID로 로그를 쿼리할 수 있습니다. 결과는 행 컬렉션이 있는 테이블로 반환됩니다.

작업 영역 중심 로그 쿼리

작업 영역 ID로 쿼리하려면 다음 방법을 사용합니다.LogsQueryClient.queryWorkspace

import { LogsQueryClient, Durations, LogsQueryResultStatus } from "@azure/monitor-query-logs";
import { DefaultAzureCredential } from "@azure/identity";

const azureLogAnalyticsWorkspaceId = "<workspace_id>";
const logsQueryClient = new LogsQueryClient(new DefaultAzureCredential());

const kustoQuery = "AppEvents | limit 1";
const result = await logsQueryClient.queryWorkspace(azureLogAnalyticsWorkspaceId, kustoQuery, {
  duration: Durations.twentyFourHours,
});

if (result.status === LogsQueryResultStatus.Success) {
  const tablesFromResult = result.tables;

  if (tablesFromResult.length === 0) {
    console.log(`No results for query '${kustoQuery}'`);
    return;
  }
  console.log(`This query has returned table(s) - `);
  processTables(tablesFromResult);
} else {
  console.log(`Error processing the query '${kustoQuery}' - ${result.partialError}`);
  if (result.partialTables.length > 0) {
    console.log(`This query has also returned partial data in the following table(s) - `);
    processTables(result.partialTables);
  }
}

리소스 중심 로그 쿼리

다음 예제에서는 Azure 리소스에서 직접 로그를 쿼리하는 방법을 보여 줍니다. queryResource 여기서는 메서드가 사용되고 Azure 리소스 ID가 전달됩니다. 예: /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}.

리소스 ID를 찾으려면:

1. Azure Portal에서 리소스의 페이지로 이동합니다.
2. 개요 블레이드에서 JSON 보기 링크를 선택합니다.
3. 결과 JSON에서 속성의 값을 id 복사합니다.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, Durations, LogsQueryResultStatus } from "@azure/monitor-query-logs";

const logsResourceId = "<the Resource Id for your logs resource>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kustoQuery = `MyTable_CL | summarize count()`;

console.log(`Running '${kustoQuery}' over the last One Hour`);
const queryLogsOptions = {
  // explicitly control the amount of time the server can spend processing the query.
  serverTimeoutInSeconds: 600, // sets the timeout to 10 minutes
  // optionally enable returning additional statistics about the query's execution.
  // (by default, this is off)
  includeQueryStatistics: true,
};

const result = await logsQueryClient.queryResource(
  logsResourceId,
  kustoQuery,
  { duration: Durations.sevenDays },
  queryLogsOptions,
);

console.log(`Results for query '${kustoQuery}'`);

if (result.status === LogsQueryResultStatus.Success) {
  const tablesFromResult = result.tables;

  if (tablesFromResult.length === 0) {
    console.log(`No results for query '${kustoQuery}'`);
    return;
  }
  console.log(`This query has returned table(s) - `);
  processTables(tablesFromResult);
} else {
  console.log(`Error processing the query '${kustoQuery}' - ${result.partialError}`);
  if (result.partialTables.length > 0) {
    console.log(`This query has also returned partial data in the following table(s) - `);
    processTables(result.partialTables);
  }
}

로그 쿼리 응답 처리

queryWorkspace 의 LogsQueryClient 함수는 객체를 반환합니다LogsQueryResult. 개체 유형은 또는 LogsQuerySuccessfulResult일 수 LogsQueryPartialResult 있습니다. 응답의 계층 구조는 다음과 같습니다.

LogsQuerySuccessfulResult
|---statistics
|---visualization
|---status ("Success")
|---tables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

LogsQueryPartialResult
|---statistics
|---visualization
|---status ("PartialFailure")
|---partialError
    |--name
    |--code
    |--message
    |--stack
|---partialTables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

예를 들어 테이블을 사용하여 응답을 처리하려면 다음을 수행합니다.

function processTables(tablesFromResult) {
  for (const table of tablesFromResult) {
    const columnHeaderString = table.columnDescriptors
      .map((column) => `${column.name}(${column.type}) `)
      .join("| ");
    console.log("| " + columnHeaderString);
    for (const row of table.rows) {
      const columnValuesString = row.map((columnValue) => `'${columnValue}' `).join("| ");
      console.log("| " + columnValuesString);
    }
  }
}

전체 샘플은 여기에서 찾을 수 있습니다.

Batch 로그 쿼리

다음 예제에서는 일괄 처리 쿼리 API를 사용하여 동시에 여러 쿼리를 보내는 방법을 보여 줍니다. 쿼리는 개체 목록으로 BatchQuery 나타낼 수 있습니다.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, LogsQueryResultStatus } from "@azure/monitor-query-logs";

const monitorWorkspaceId = "<workspace_id>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kqlQuery = "AppEvents | project TimeGenerated, Name, AppRoleInstance | limit 1";
const queriesBatch = [
  {
    workspaceId: monitorWorkspaceId,
    query: kqlQuery,
    timespan: { duration: "P1D" },
  },
  {
    workspaceId: monitorWorkspaceId,
    query: "AzureActivity | summarize count()",
    timespan: { duration: "PT1H" },
  },
  {
    workspaceId: monitorWorkspaceId,
    query:
      "AppRequests | take 10 | summarize avgRequestDuration=avg(DurationMs) by bin(TimeGenerated, 10m), _ResourceId",
    timespan: { duration: "PT1H" },
  },
  {
    workspaceId: monitorWorkspaceId,
    query: "AppRequests | take 2",
    timespan: { duration: "PT1H" },
    includeQueryStatistics: true,
  },
];

const result = await logsQueryClient.queryBatch(queriesBatch);

if (result == null) {
  throw new Error("No response for query");
}

let i = 0;
for (const response of result) {
  console.log(`Results for query with query: ${queriesBatch[i]}`);
  if (response.status === LogsQueryResultStatus.Success) {
    console.log(
      `Printing results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
    );
    processTables(response.tables);
  } else if (response.status === LogsQueryResultStatus.PartialFailure) {
    console.log(
      `Printing partial results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
    );
    processTables(response.partialTables);
    console.log(
      ` Query had errors:${response.partialError.message} with code ${response.partialError.code}`,
    );
  } else {
    console.log(`Printing errors from query '${queriesBatch[i].query}'`);
    console.log(` Query had errors:${response.message} with code ${response.code}`);
  }
  // next query
  i++;
}

로그 일괄 처리 쿼리 응답 처리

queryBatch 의 LogsQueryClient 함수는 객체를 반환합니다LogsQueryBatchResult. LogsQueryBatchResult 에는 다음과 같은 가능한 유형의 개체 목록이 포함되어 있습니다.

• LogsQueryPartialResult
• LogsQuerySuccessfulResult
• LogsQueryError

응답의 계층 구조는 다음과 같습니다.

LogsQuerySuccessfulResult
|---statistics
|---visualization
|---status ("Success")
|---tables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

LogsQueryPartialResult
|---statistics
|---visualization
|---status ("PartialFailure")
|---partialError
    |--name
    |--code
    |--message
    |--stack
|---partialTables (list of `LogsTable` objects)
    |---name
    |---rows
    |---columnDescriptors (list of `LogsColumn` objects)
        |---name
        |---type

LogsQueryError
|--name
|--code
|--message
|--stack
|--status ("Failure")

예를 들어 다음 코드는 일괄 처리 로그 쿼리 응답을 처리합니다.

import { LogsQueryResultStatus } from "@azure/monitor-query-logs";

async function processBatchResult(result, queriesBatch) {
  let i = 0;
  for (const response of result) {
    console.log(`Results for query with query: ${queriesBatch[i]}`);
    if (response.status === LogsQueryResultStatus.Success) {
      console.log(
        `Printing results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
      );
      processTables(response.tables);
    } else if (response.status === LogsQueryResultStatus.PartialFailure) {
      console.log(
        `Printing partial results from query '${queriesBatch[i].query}' for '${queriesBatch[i].timespan}'`,
      );
      processTables(response.partialTables);
      console.log(
        ` Query had errors:${response.partialError.message} with code ${response.partialError.code}`,
      );
    } else {
      console.log(`Printing errors from query '${queriesBatch[i].query}'`);
      console.log(` Query had errors:${response.message} with code ${response.code}`);
    }
    // next query
    i++;
  }
}
function processTables(tablesFromResult) {
  for (const table of tablesFromResult) {
    const columnHeaderString = table.columnDescriptors
      .map((column) => `${column.name}(${column.type}) `)
      .join("| ");
    console.log("| " + columnHeaderString);
    for (const row of table.rows) {
      const columnValuesString = row.map((columnValue) => `'${columnValue}' `).join("| ");
      console.log("| " + columnValuesString);
    }
  }
}

전체 샘플은 여기에서 찾을 수 있습니다.

고급 로그 쿼리 시나리오

로그 쿼리 시간 제한 설정

일부 로그 쿼리를 실행하는 데 3분 이상 걸립니다. 기본 서버 시간 제한은 3분입니다. 서버 시간 제한을 최대 10분으로 늘릴 수 있습니다. 다음 예제에서는 LogsQueryOptions 개체의 serverTimeoutInSeconds 속성을 사용하여 서버 시간 제한을 10분으로 늘립니다.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";

const azureLogAnalyticsWorkspaceId = "<workspace_id>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kqlQuery = "AppEvents | project TimeGenerated, Name, AppRoleInstance | limit 1";

// setting optional parameters
const queryLogsOptions = {
  // explicitly control the amount of time the server can spend processing the query.
  serverTimeoutInSeconds: 600, // 600 seconds = 10 minutes
};

const result = await logsQueryClient.queryWorkspace(
  azureLogAnalyticsWorkspaceId,
  kqlQuery,
  { duration: Durations.twentyFourHours },
  queryLogsOptions,
);

const status = result.status;

여러 작업 영역 쿼리

여러 Log Analytics 작업 영역에서 동일한 로그 쿼리를 실행할 수 있습니다. Kusto 쿼리 외에도 다음 매개 변수가 필요합니다.

• workspaceId - 첫 번째(기본) 워크스페이스 ID입니다.
• additionalWorkspaces - 매개변수에 workspaceId 제공된 작업 공간을 제외한 작업 공간 목록입니다. 매개 변수의 목록 항목은 다음 식별자 형식으로 구성됩니다.
  • 정규화된 작업 영역 이름
  • 작업 영역 ID
  • Azure 리소스 ID

예를 들어 다음 쿼리는 세 개의 작업 영역에서 실행됩니다.

import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";

const azureLogAnalyticsWorkspaceId = "<workspace_id>";

const tokenCredential = new DefaultAzureCredential();
const logsQueryClient = new LogsQueryClient(tokenCredential);

const kqlQuery = "AppEvents | project TimeGenerated, Name, AppRoleInstance | limit 1";

// setting optional parameters
const queryLogsOptions = {
  additionalWorkspaces: ["<workspace2>", "<workspace3>"],
};

const result = await logsQueryClient.queryWorkspace(
  azureLogAnalyticsWorkspaceId,
  kqlQuery,
  { duration: Durations.twentyFourHours },
  queryLogsOptions,
);

const status = result.status;

각 작업 영역에 대한 결과를 보려면 열을 사용하여 TenantId 결과를 정렬하거나 Kusto 쿼리에서 필터링합니다.

TenantId별 주문 결과

AppEvents | order by TenantId

TenantId를 기준으로 결과 필터링

AppEvents | filter TenantId == "<workspace2>"

전체 샘플은 여기에서 찾을 수 있습니다.

통계 포함

로그 쿼리 실행 통계(예: CPU 및 메모리 사용량)를 얻으려면 다음을 수행합니다.

1. LogsQueryOptions.includeQueryStatistics 속성을 true으로 설정합니다.
2. statistics 개체 내부의 LogsQueryResult 필드에 액세스합니다.

다음 예제에서는 쿼리 실행 시간을 인쇄합니다.

import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";
import { DefaultAzureCredential } from "@azure/identity";

const monitorWorkspaceId = "<workspace_id>";
const logsQueryClient = new LogsQueryClient(new DefaultAzureCredential());
const kustoQuery = "AzureActivity | top 10 by TimeGenerated";

const result = await logsQueryClient.queryWorkspace(
  monitorWorkspaceId,
  kustoQuery,
  { duration: Durations.oneDay },
  {
    includeQueryStatistics: true,
  },
);

console.log(`Results for query '${kustoQuery}'`);

페이로드의 statistics 구조는 쿼리 Record<string, unknown> 에 따라 다르기 때문에 반환 형식이 사용됩니다. 원시 JSON 응답을 포함합니다. 통계는 JSON의 속성 내에서 query 찾을 수 있습니다. 다음은 그 예입니다.

{
  "query": {
    "executionTime": 0.0156478,
    "resourceUsage": {...},
    "inputDatasetStatistics": {...},
    "datasetStatistics": [{...}]
  }
}

시각화 포함

렌더링 연산자를 사용하여 로그 쿼리에 대한 시각화 데이터를 가져오려면:

1. LogsQueryOptions.includeVisualization 속성을 true으로 설정합니다.
2. visualization 개체 내부의 LogsQueryResult 필드에 액세스합니다.

다음은 그 예입니다.

import { LogsQueryClient, Durations } from "@azure/monitor-query-logs";
import { DefaultAzureCredential } from "@azure/identity";

const monitorWorkspaceId = "<workspace_id>";
const logsQueryClient = new LogsQueryClient(new DefaultAzureCredential());

const result = await logsQueryClient.queryWorkspace(
  monitorWorkspaceId,
  `StormEvents
        | summarize event_count = count() by State
        | where event_count > 10
        | project State, event_count
        | render columnchart`,
  { duration: Durations.oneDay },
  {
    includeVisualization: true,
  },
);

console.log("visualization result:", result.visualization);

페이로드의 visualization 구조는 쿼리 Record<string, unknown> 에 따라 다르기 때문에 반환 형식이 사용됩니다. 원시 JSON 응답을 포함합니다. 다음은 그 예입니다.

{
  "visualization": "columnchart",
  "title": "the chart title",
  "accumulate": false,
  "isQuerySorted": false,
  "kind": null,
  "legend": null,
  "series": null,
  "yMin": "NaN",
  "yMax": "NaN",
  "xAxis": null,
  "xColumn": null,
  "xTitle": "x axis title",
  "yAxis": null,
  "yColumns": null,
  "ySplit": null,
  "yTitle": null,
  "anomalyColumns": null
}

문제 해결

다양한 오류 시나리오를 진단하려면 문제 해결 가이드를 참조하세요.

다음 단계

Azure Monitor에 대한 자세한 내용은 Azure Monitor 서비스 설명서를 참조하세요.

기여하기

이 라이브러리에 기여하려면 기여 가이드 읽어 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

이 모듈의 테스트는 라이브 테스트와 단위 테스트가 혼합되어 있으므로 Azure Monitor 인스턴스가 있어야 합니다. 테스트를 실행하려면 다음을 실행해야 합니다.

1. rush update
2. rush build -t @azure/monitor-query-logs
3. cd into sdk/monitor/monitor-query
4. sample.env 파일을 복사 합니다..env
5. 편집기에서 파일을 .env 열고 값을 입력합니다.
6. npm run test;

자세한 내용은 테스트 폴더를 참조하십시오.

관련 프로젝트

• JavaScript용 Microsoft Azure SDK
• Azure Monitor