【合入来源】

如有社区issue，请关联issue链接
请勿携带内部流程信息（需求链接、问题单、内部issue等）

• 需求
• 问题单
• issue/工单
• 重构优化
• 资料更新
  pytorch 社区用例没有验证 torch.distributed.elastic.metrics.api.ConsoleMetricHandler、torch.distributed.elastic.metrics.api.NullMetricHandler 和 torch.distributed.elastic.metrics.configure，故新增该测试用例文件，用于验证这三个 API 的正确性。

【修改方案】

一、API 功能说明

1. torch.distributed.elastic.metrics.api.ConsoleMetricHandler
   是 PyTorch 分布式弹性训练 metrics 模块下的指标输出处理器，核心功能如下：
   控制台输出能力：通过 emit(metric_data) 接收 MetricData 指标对象，并将指标内容输出到控制台。
   指标字段承载能力：可处理包含 timestamp、group_name、name、value 等字段的 MetricData 对象。
   Handler 基类兼容：ConsoleMetricHandler 是 MetricHandler 类型实例，可作为 metrics 模块统一的指标处理器使用。
   与 configure 联动：配置为默认 handler 或指定 group handler 后，可通过 metrics_api.getStream(...).add_value(...) 触发指标输出。

2.torch.distributed.elastic.metrics.api.NullMetricHandler
是 PyTorch 分布式弹性训练 metrics 模块下的空指标处理器，核心功能如下：
空处理能力：通过 emit(metric_data) 接收 MetricData 指标对象，但不产生控制台输出。
无副作用返回：调用 emit 后返回 None，不会打印内容。
Handler 基类兼容：NullMetricHandler 是 MetricHandler 类型实例，可作为 metrics 模块统一的指标处理器使用。
与 configure 联动：配置为默认 handler 或指定 group handler 后，可屏蔽对应指标流的输出。

3.torch.distributed.elastic.metrics.configure
是 PyTorch 分布式弹性训练 metrics 模块下的指标处理器配置 API，核心功能如下：
默认 handler 配置：调用 configure(handler) 时，可配置全局默认 metrics handler。
group 级 handler 配置：调用 configure(handler, group="xxx") 时，可为指定 group 单独配置 metrics handler。
指标流分发能力：通过 metrics_api.getStream(group_name).add_value(metric_name, value) 上报指标时，会按照 group 配置选择对应 handler。
默认与 group 配置隔离：指定 group 的 handler 只影响对应 group，不影响其他 group 使用默认 handler。

二、测试文件 test_metrics_api.py 完整验证该 API 的原因

该测试用例针对 ConsoleMetricHandler、NullMetricHandler 和 configure 三个 API 进行验证，覆盖 handler 基础行为、默认配置、group 级配置和测试隔离性。

对 ConsoleMetricHandler 的验证
test_console_metric_handler_emit：验证 ConsoleMetricHandler.emit 能正常接收 MetricData，返回值为 None，并通过 print 输出包含 timestamp/value、group name 和 metric name 的指标信息；同时验证 ConsoleMetricHandler 是 MetricHandler 的实例。
对 NullMetricHandler 的验证
test_null_metric_handler_emit：验证 NullMetricHandler.emit 能正常接收 MetricData，返回值为 None，且不会触发任何控制台输出；同时验证 NullMetricHandler 是 MetricHandler 的实例。
对 configure 默认 handler 配置的验证
test_configure_default_console_metric_handler：验证通过 configure(handler) 将默认 handler 配置为 ConsoleMetricHandler 后，调用 metrics_api.getStream(...).add_value(...) 能正常触发控制台输出。
test_configure_default_null_metric_handler：验证通过 configure(handler) 将默认 handler 配置为 NullMetricHandler 后，调用 metrics_api.getStream(...).add_value(...) 不会产生控制台输出，且返回值为 None。
对 configure group 级 handler 配置的验证
test_configure_group_specific_console_metric_handler：验证为指定 group 配置 ConsoleMetricHandler 后，仅该 group 的指标会上报到控制台，默认 group 仍使用默认 handler，二者互不干扰。
test_configure_group_specific_null_metric_handler：验证为指定 group 配置 NullMetricHandler 后，仅该 group 的指标不会输出，其他 group 仍可使用默认 ConsoleMetricHandler 正常输出。
测试隔离性保障
setUp 和 _restore_metrics_state：在每个测试前保存原始 _default_metrics_handler 和 _metrics_map，测试结束后恢复全局 metrics 状态，避免不同测试用例之间的 handler 配置互相污染。

综上，该文件覆盖了 ConsoleMetricHandler 的控制台输出行为、NullMetricHandler 的空处理行为、configure 的默认 handler 配置能力、group 级 handler 配置能力，以及测试间全局状态隔离能力，是对这三个 metrics API 的基础功能验证。

三、NPU适配
torch.distributed.elastic.metrics.api.ConsoleMetricHandler、torch.distributed.elastic.metrics.api.NullMetricHandler 和 torch.distributed.elastic.metrics.configure 均具备硬件无关性、纯 Python 层实现、无底层算子依赖三大核心特征，决定了其无需针对昇腾 NPU 做修改

【资料变更】

不涉及

【接口变更】

不涉及

【功能验证】

在2.10.0版本上执行该用例，均通过，日志如下：
[root@82bc9d38ec90 workspace]# python /workspace/2.10.0/pytorch/test/distributed/elastic/metrics/test_metrics_api.py
......
Ran 6 tests in 0.037s

OK

【CheckList】

PR提交人对以下CheckList自检项进行全量自检，自检通过或不涉及，均修改 [ ] 为 [x]

• 代码注释完备，正确记录错误日志
• 代码实现进行了返回值、空指针等校验
• PR标题正确使用类型标签，如：feat、fix、refactor、docs、test等
• PR持续集成流水线（CI）执行通过，代码检查无异常