# @azure/monitor-query 中文文档

规范地址：https://npmcn.com/package/%40azure/monitor-query/

版本：1\.3\.3
npm 元数据更新时间：2026-03-19T19:53:13.147Z
中文译文更新时间：2026-11-07T13:23:23.790Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azure/monitor-query
原文对照：https://npmcn.com/package/%40azure/monitor-query/?lang=original
项目主页：https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/README.md
源码仓库：https://github.com/Azure/azure-sdk-for-js

弃用说明：Deprecated ⚠️: use @azure/monitor-query-logs, @azure/monitor-query-metrics and @azure/arm-monitor\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.3 MB，1096 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：8 个
- 首次发布：2021-05-28T20:36:01.741Z
- 最新版本发布：2025-08-12T22:09:09.893Z
- 近 30 天下载量：349049（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

折旧:使用@azure/monitor-query-logs、@azure/monitor-query-medicers和@azure/arm-monitor.

## 安装

```sh
npm install @azure/monitor-query
```

也可以使用：`pnpm add @azure/monitor-query`、`yarn add @azure/monitor-query`、`bun add @azure/monitor-query`

## README

## 已贬值 QQ:本套件已经贬值,不再积极开发. 请迁移到以下软件包:

> -   `LogsQueryClient`数字 : `@azure/monitor-query-logs` - 移徙指南: [监视查询日志迁移](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query-logs/MIGRATION.md) • 无: [@azure/monitor-query-logs (韩语)](https://www.npmjs.com/package/@azure/monitor-query-logs)
> -   `MetricsClient`数字 : `@azure/monitor-query-metrics` - 移徙指南: [监视查询量表迁移](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query-metrics/MIGRATION.md) • 无: [@azure/monitor-query-度量衡](https://www.npmjs.com/package/@azure/monitor-query-metrics)
> -   `MetricsQueryClient`: 迁移到管理库 `@azure/arm-monitor` - 向导: [@azure/arm-监视器](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/arm-monitor/MIGRATION_METRICSQUERYCLIENT_TO_ARM_MONITOR.md)
> 
> 上面列出的替换库会添加新的特性和不安全的错误修正.

Azure 监视器查询客户端库用于执行只读查询 [Azure 监视器](https://learn.microsoft.com/azure/azure-monitor/overview)其两个数据平台:

-   [日志](https://learn.microsoft.com/azure/azure-monitor/logs/data-platform-logs) - 收集和组织来自监测资源的记录和业绩数据。 来自不同来源的数据,如来自Azure服务的平台日志,来自虚拟机代理机的日志和性能数据,以及来自app的用法和性能数据可以被整合为单一数据 [Azure 日志分析工作空间](https://learn.microsoft.com/azure/azure-monitor/logs/data-platform-logs#log-analytics-and-workspaces)。可以使用 [Kusto 查询语言](https://learn.microsoft.com/azure/data-explorer/kusto/query/)。 。 。 .
-   [计量](https://learn.microsoft.com/azure/azure-monitor/essentials/data-platform-metrics) - 从监测资源中收集数字数据,输入时间序列数据库。 量子是定期收集的数值并描述一个系统在特定时间的某些方面. 量子是轻而易举的,能够支持近实时的情景,使其对提醒和快速发现问题有用.

**资源:**

-   [源代码](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/)
-   [软件包( npm)](https://www.npmjs.com/package/@azure/monitor-query)
-   [API 参考文件](https://learn.microsoft.com/javascript/api/@azure/monitor-query)
-   [服务文件](https://learn.microsoft.com/azure/azure-monitor/overview)
-   [样本](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/monitor/monitor-query/samples)
-   [更改日志](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/CHANGELOG.md)

## 开始

### 支持的环境

-   [节点.js的LTS版本](https://github.com/nodejs/release#release-schedule)
-   Safari、Chrome、Microsoft Edge和Firefox的最新版本

详情请见我们 [支助政策](https://github.com/Azure/azure-sdk-for-js/blob/main/SUPPORT.md)。 。 。 .

### 先决条件

-   一个 [Azure 订阅](https://azure.microsoft.com/free/)
-   A 类 [证书](https://learn.microsoft.com/javascript/api/@azure/core-auth/tokencredential?view=azure-node-latest) 执行,例如 [Azure 身份库证书类型](https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes)。 。 。 .
-   要查询日志, 您需要下列操作之一 :
    -   一个 [Azure 日志分析工作空间](https://learn.microsoft.com/azure/azure-monitor/logs/quick-create-workspace)
    -   任何类型的 Azure 资源( 套接字账户、 密钥断层、 Cosmos DB等)
-   要查询 Metrics,您需要任何类型的 Azure 资源(Storage Counter, Key Vault, Cosmos DB等) .

### 安装软件包

为 npm 安装 Azure 监视器查询客户端库 :

```bash
npm install --save @azure/monitor-query
```

### 创建客户端

需要经认证的客户端查询日志或计量。 要认证,以下示例使用 [默认标记](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/identity/identity/README.md#defaultazurecredential) 从 [@azure/身份](https://www.npmjs.com/package/@azure/identity) 软件包.

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, MetricsQueryClient, MetricsClient } from "@azure/monitor-query";

const credential = new DefaultAzureCredential();

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

// Create a MetricsQueryClient
const metricsQueryClient = new MetricsQueryClient(credential);

// Create a MetricsClient
const endpoint = " https://<endpoint>.monitor.azure.com/";
const metricsClient = new MetricsClient(endpoint, credential);
```

#### Azure 主权云配置客户端

默认情况下,图书馆的客户端被配置为使用Azure公共云. 取而代之的是使用主权云,在即时处理客户端时提供正确的端点和受众值. 例如:

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { LogsQueryClient, MetricsQueryClient, MetricsClient } from "@azure/monitor-query";

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

// Create a MetricsQueryClient
const metricsQueryClient: MetricsQueryClient = new MetricsQueryClient(credential, {
  endpoint: "https://management.chinacloudapi.cn",
  audience: "https://monitor.azure.cn/.default",
});

// Create a MetricsClient
const endpoint = " https://<endpoint>.monitor.azure.cn/";
const metricsClient = new MetricsClient(endpoint, credential, {
  audience: "https://monitor.azure.cn/.default",
});
```

**说明**:目前, `MetricsQueryClient` 使用 Azure 资源管理器(ARM) 的端点进行查询。 您使用此客户端时需要相应的管理端点 。 这一细节将来会有所改变.

### 执行查询

关于日志和计量查询的例子,请参见 [实例](https://npmcn.com/package/%40azure/monitor-query/#readme-examples) 节.

## 关键概念

### 日志查询率限制和节奏

逻辑分析服务在请求率过高时采用节流. 限制,如返回行数的上限,也适用于库斯多查询. 更多信息见 [查询 API](https://learn.microsoft.com/azure/azure-monitor/service-limits#la-query-api)。 。 。 .

### 计量数据结构

每组度量值是一个时间序列,具有以下特征: 1

-   值被收集的时间
-   与数值相关的资源
-   名称空格, 类似于测量的分类
-   一个参数名称
-   值本身
-   一些度量衡具有多维度,如多维度量法所描述. 定制度量衡可达10维.

## 实例

-   [日志查询](https://npmcn.com/package/%40azure/monitor-query/#readme-logs-query)
    -   [以工作空间为中心的日志查询](https://npmcn.com/package/%40azure/monitor-query/#readme-workspace-centric-logs-query)
    -   [以资源为中心的日志查询](https://npmcn.com/package/%40azure/monitor-query/#readme-resource-centric-logs-query)
    -   [处理日志查询回复](https://npmcn.com/package/%40azure/monitor-query/#readme-handle-logs-query-response)
-   [批量日志查询](https://npmcn.com/package/%40azure/monitor-query/#readme-batch-logs-query)
    -   [处理日志批次查询回复](https://npmcn.com/package/%40azure/monitor-query/#readme-handle-logs-batch-query-response)
-   [高级日志查询方案](https://npmcn.com/package/%40azure/monitor-query/#readme-advanced-logs-query-scenarios)
    -   [设置日志查询超时](https://npmcn.com/package/%40azure/monitor-query/#readme-set-logs-query-timeout)
    -   [查询多个工作空间](https://npmcn.com/package/%40azure/monitor-query/#readme-query-multiple-workspaces)
    -   [包含统计数据](https://npmcn.com/package/%40azure/monitor-query/#readme-include-statistics)
    -   [包含可视化](https://npmcn.com/package/%40azure/monitor-query/#readme-include-visualization)
-   [度量衡查询](https://npmcn.com/package/%40azure/monitor-query/#readme-metrics-query)
    -   [处理参数查询答复](https://npmcn.com/package/%40azure/monitor-query/#readme-handle-metrics-query-response)
    -   [处理答复实例](https://npmcn.com/package/%40azure/monitor-query/#readme-example-of-handling-response)
    -   [查询多种资源的指标](https://npmcn.com/package/%40azure/monitor-query/#readme-query-metrics-for-multiple-resources)

### 日志查询

这个 `LogsQueryClient` 用于查询日志分析工作空间 [Kusto 查询语言](https://learn.microsoft.com/azure/data-explorer/kusto/query/)编辑 `timespan.duration` 可以用ISO 8601持续时间格式指定字符串。 你可以用这个 `Durations` 为一些常用的ISO 8601持续时间提供的常数.

您可以通过 Log Analytics 工作空间ID 或 Azure 资源ID 查询日志 。 结果以一表还原并有行集.

#### 以工作空间为中心的日志查询

要通过工作区ID查询,请使用 `LogsQueryClient.queryWorkspace` 方法 :

```ts
import { LogsQueryClient, Durations, LogsQueryResultStatus } from "@azure/monitor-query";
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);
  }
}

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

#### 以资源为中心的日志查询

以下例子说明如何直接从Azure资源查询日志。 在这里 `queryResource` 使用Azure资源ID。 譬如说, `/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider}/{resource-type}/{resource-name}`。 。 。 .

要找到资源标识 :

1.  在 Azure 门户网站中导航您的资源页面 .
2.  从 **概览** 刀片,选择 **JSON 视图** 链接.
3.  在生成的 JSON 中,复制 `id` 属性.

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

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

const executionTime = (result as any)?.statistics?.query?.executionTime;

console.log(
  `Results for query '${kustoQuery}', execution time: ${executionTime == null ? "unknown" : executionTime}`,
);

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

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

#### 处理日志查询回复

这个 `queryWorkspace` 函数 `LogsQueryClient` 返回 a `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
```

例如,用表格处理回复:

```ts
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);
    }
  }
}
```

可以找到完整的样本 [这里](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/samples/v1/typescript/src/logsQuery.ts)。 。 。 .

### 批量日志查询

以下例子表明同时使用批量查询API发送多个查询. 查询可列作以下列表: `BatchQuery` 对象.

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

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++;
}

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

#### 处理日志批次查询回复

这个 `queryBatch` 函数 `LogsQueryClient` 返回 a `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")
```

例如,以下代码处理批次日志查询响应:

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

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

可以找到完整的样本 [这里](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/samples/v1/typescript/src/logsQueryBatch.ts)。 。 。 .

### 高级日志查询方案

#### 设置日志查询超时

一些日志查询需要超过3分钟才能执行. 默认服务器超时为3分钟. 您可以将服务器超时时间增加到最多10分钟. 例如 `LogsQueryOptions` 对象的 `serverTimeoutInSeconds` 属性用于将服务器超时到 10 分钟 :

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

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

#### 查询多个工作空间

同样的日志查询可以在多个日志分析工作空间中执行. 除了库斯多查询外,还需要以下参数: 1

-   `workspaceId` - 第一个(初级)工作空间身份证.
-   `additionalWorkspaces` - 工作空间清单,不包括: `workspaceId` 参数。 参数的列表项目可以由以下标识格式组成:
    -   合格的工作空间名称
    -   工作空间标识
    -   Azure 资源标识

例如,以下查询在三个工作空间执行:

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

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 查询中过滤结果.

**租户的订单结果**

```
AppEvents | order by TenantId
```

**由租户过滤结果**

```
AppEvents | filter TenantId == "<workspace2>"
```

可以找到完整的样本 [这里](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/samples/v1/typescript/src/logsQueryMultipleWorkspaces.ts)。 。 。 .

#### 包含统计数据

要获取日志查询执行统计, 如 CPU 和内存消耗 :

1.  设定 `LogsQueryOptions.includeQueryStatistics` 属性改为 `true`。 。 。 .
2.  进入 `statistics` 字段内 `LogsQueryResult` 对象.

以下示例打印了查询执行时间 :

```ts
import { LogsQueryClient, Durations } from "@azure/monitor-query";
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,
  },
);

const executionTime = (result as any)?.statistics?.query?.executionTime;

console.log(
  `Results for query '${kustoQuery}', execution time: ${executionTime == null ? "unknown" : executionTime}`,
);
```

因为结构 `statistics` 有效载荷因查询而异, a `Record<string, unknown>` 返回类型被使用。 它包含原始JSON反应. 这些统计数字见于本报告 `query` jSON的财产。 例如:

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

#### 包含可视化

使用 [渲染运算符](https://learn.microsoft.com/azure/data-explorer/kusto/query/renderoperator?pivots=azuremonitor)数字 :

1.  设定 `LogsQueryOptions.includeVisualization` 属性改为 `true`。 。 。 .
2.  进入 `visualization` 字段内 `LogsQueryResult` 对象.

例如:

```ts
import { LogsQueryClient, Durations } from "@azure/monitor-query";
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` 有效载荷因查询而异, a `Record<string, unknown>` 返回类型被使用。 它包含原始JSON反应. 例如:

```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计量学顾问](https://learn.microsoft.com/azure/applied-ai-services/metrics-advisor/overview) 订阅. URI必须是正在被问及的度量衡资源。 一般都是这样 `/subscriptions/<id>/resourceGroups/<rg-name>/providers/<source>/topics/<resource-name>`。 。 。 .

要找到资源 URI :

1.  在 Azure 门户网站中导航您的资源页面 .
2.  从 **概览** 刀片,选择 **JSON 视图** 链接.
3.  在生成的 JSON 中,复制 `id` 属性.

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { MetricsQueryClient, Durations } from "@azure/monitor-query";

const metricsResourceId = "<the Resource Id for your metrics resource>";

const tokenCredential = new DefaultAzureCredential();
const metricsQueryClient = new MetricsQueryClient(tokenCredential);

const metricNames = [];
const metricDefinitions = metricsQueryClient.listMetricDefinitions(metricsResourceId);
for await (const { id, name } of metricDefinitions) {
  console.log(` metricDefinitions - ${id}, ${name}`);
  if (name) {
    metricNames.push(name);
  }
}

const [firstMetricName, secondMetricName] = metricNames;
if (firstMetricName && secondMetricName) {
  console.log(`Picking an example metric to query: ${firstMetricName} and ${secondMetricName}`);
  const metricsResponse = await metricsQueryClient.queryResource(
    metricsResourceId,
    [firstMetricName, secondMetricName],
    {
      granularity: "PT1M",
      timespan: { duration: Durations.fiveMinutes },
    },
  );

  console.log(
    `Query cost: ${metricsResponse.cost}, interval: ${metricsResponse.granularity}, time span: ${metricsResponse.timespan}`,
  );

  const metrics = metricsResponse.metrics;
  console.log(`Metrics:`, JSON.stringify(metrics, undefined, 2));
  const metric = metricsResponse.getMetricByName(firstMetricName);
  console.log(`Selected Metric: ${firstMetricName}`, JSON.stringify(metric, undefined, 2));
} else {
  console.error(`Metric names are not defined - ${firstMetricName} and ${secondMetricName}`);
}
```

在上述抽样中,衡量结果如下: `metricsResponse` 按照用户在定义中指定公尺名称的顺序排序 `metricNames` 矩阵参数 `queryResource` 函数。 如果用户指定 `[firstMetricName, secondMetricName]`,结果 `firstMetricName` 将在结果前显示 `secondMetricName` 输入 `metricResponse`。 。 。 .

#### 处理参数查询答复

衡量标准 `queryResource` 函数返回 a `QueryMetricsResult` 对象。 这个 `QueryMetricsResult` 对象包含诸如列表等属性 `Metric`\- 型号物体, `interval`, (中文(简体) ), `namespace`,以及 `timespan`编辑 `Metric` 对象列表可以使用 `metrics` 属性。 每个 `Metric` 此列表中的对象包含一个列表 `TimeSeriesElement` 对象。 每个 `TimeSeriesElement` 包含 `data` 财务报告和审定财务报表 `metadataValues` 属性。 在视觉形式上,反应对象的分层结构类似于以下结构: 反应对象的分层结构是:

```
QueryMetricsResult
|---cost
|---timespan (of type `QueryTimeInterval`)
|---granularity
|---namespace
|---resourceRegion
|---metrics (list of `Metric` objects)
    |---id
    |---type
    |---name
    |---unit
    |---displayDescription
    |---errorCode
    |---timeseries (list of `TimeSeriesElement` objects)
        |---metadataValues
        |---data (list of data points represented by `MetricValue` objects)
            |---timeStamp
            |---average
            |---minimum
            |---maximum
            |---total
            |---count
|---getMetricByName(metricName): Metric | undefined (convenience method)
```

#### 处理答复实例

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { MetricsQueryClient, Durations } from "@azure/monitor-query";

const metricsResourceId = "<the Resource Id for your metrics resource>";

const tokenCredential = new DefaultAzureCredential();
const metricsQueryClient = new MetricsQueryClient(tokenCredential);

console.log(`Picking an example metric to query: MatchedEventCount`);

const metricsResponse = await metricsQueryClient.queryResource(
  metricsResourceId,
  ["MatchedEventCount"],
  {
    timespan: {
      duration: Durations.fiveMinutes,
    },
    granularity: "PT1M",
    aggregations: ["Count"],
  },
);

console.log(
  `Query cost: ${metricsResponse.cost}, granularity: ${metricsResponse.granularity}, time span: ${metricsResponse.timespan}`,
);

const metrics = metricsResponse.metrics;
for (const metric of metrics) {
  console.log(metric.name);
  for (const timeseriesElement of metric.timeseries) {
    for (const metricValue of timeseriesElement.data!) {
      if (metricValue.count !== 0) {
        console.log(`There are ${metricValue.count} matched events at ${metricValue.timeStamp}`);
      }
    }
  }
}
```

可以找到完整的样本 [这里](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/samples/v1/typescript/src/metricsQuery.ts)。 。 。 .

#### 查询多种资源的指标

要查询单个请求中多个Azure资源的计量标准,请使用 `MetricsClient.queryResources` 方法。 这种方法 :

-   调用一个不同的 API 而非 `MetricsClient` 方法。 。 .
-   创建客户端时需要区域终点 。 例如"https://westus3.meterics.monitor.azure.com".

每种阿苏雷资源必须居住在:

-   创建客户端时指定的与终点相同的区域.
-   同样的Azure订阅.

此外:

-   必须授权用户读取Azure订阅级别的监测数据. 例如 [监测读者角色](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles/monitor#monitoring-reader) 关于要询问的订阅.
-   必须提供包含要询问的度量衡的计量命名空间。 参数命名空间列表见 [按资源类型分列的支助指标和日志类别](https://learn.microsoft.com/azure/azure-monitor/reference/supported-metrics/metrics-index#supported-metrics-and-log-categories-by-resource-type)。 。 。 .

```ts
import { DefaultAzureCredential } from "@azure/identity";
import { MetricsClient } from "@azure/monitor-query";

const resourceIds = [
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs",
  "/subscriptions/0000000-0000-000-0000-000000/resourceGroups/test/providers/Microsoft.OperationalInsights/workspaces/test-logs2",
];
const metricsNamespace = "<YOUR_METRICS_NAMESPACE>";
const metricNames = ["requests", "count"];
const endpoint = " https://<endpoint>.monitor.azure.com/";

const credential = new DefaultAzureCredential();
const metricsClient = new MetricsClient(endpoint, credential);

const result = await metricsClient.queryResources(resourceIds, metricNames, metricsNamespace);
```

关于每个Azure资源类型可用的计量和维度清单,见 [使用 Azure 监视器支持的度量衡](https://learn.microsoft.com/azure/azure-monitor/essentials/metrics-supported)。 。 。 .

## 解决问题

为了分析各种失败情况,请参看 [解决问题指南](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/TROUBLESHOOTING.md)。 。 。 .

## 今后的步骤

为了了解更多关于Azure监视器的信息,请参看 [Azure 监视器服务文档](https://learn.microsoft.com/azure/azure-monitor/overview)。 。 。 .

## 捐款

如果您想为图书馆捐钱 请读一下 [贡献指南](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) 学习如何构建和测试密码.

这个模块的测试是现场测试和单位测试的混合,这需要你有一个AzureMonitor实例. 为了执行测试,你需要运行:

1.  `pnpm install`
2.  `pnpm build --filter @azure/monitor-query...`
3.  `cd into sdk/monitor/monitor-query`
4.  复制 `sample.env` 文件为 `.env`
5.  打开 `.env` 在编辑器中存档并填写值.
6.  `npm run test`。 。 。 .

详情请查看我们 [测试](https://github.com/Azure/azure-sdk-for-js/blob/main/sdk/monitor/monitor-query/test) 文件夹.

## 相关项目

-   [微软 Azure SDK 用于 JavaScript](https://github.com/Azure/azure-sdk-for-js)
-   [Azure 监视器](https://learn.microsoft.com/azure/azure-monitor/overview)

## 常见问题

### @azure/monitor-query 是什么？

折旧:使用@azure/monitor-query-logs、@azure/monitor-query-medicers和@azure/arm-monitor\.注意：该包已被作者标记为弃用——Deprecated ⚠️: use @azure/monitor-query-logs, @azure/monitor-query-metrics and @azure/arm-monitor\.

### 如何安装 @azure/monitor-query？

在项目目录运行 npm install @azure/monitor-query，或使用 pnpm add / yarn add / bun add。

### @azure/monitor-query 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @azure/monitor-query 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @azure/monitor-query 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @azure/monitor-query 可以商用吗？

@azure/monitor-query 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @azure/monitor-query 的下载量有多少？

根据 npm 官方下载统计，@azure/monitor-query 在 2026/10/08 – 2026/11/06 这 30 天内被下载 349,049 次，日均约 11,635 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @azure/monitor-query 还在维护吗？

最新版本 1\.3\.3 发布于 2025/08/13（1\.2 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/05/29。作者已将其标记为弃用，新项目建议寻找替代方案。