Metrics

创建于：2021年5月4日 | 最后更新：2021年5月4日

Metrics API。

概述:

torchelastic 中的 metrics API 用于发布遥测指标。它被设计成由 torchelastic 的内部模块使用，为最终用户发布指标，目的是提高可见性和帮助调试。然而，您也可以在自己的作业中使用相同的 API，将指标发布到同一个指标 sink。

一个 metric 可以被看作是时序数据，并通过字符串元组 (metric_group, metric_name) 进行唯一标识。

torchelastic 对 metric_group 的含义及其与 metric_name 的关系不做任何假设。完全由用户来使用这两个字段来唯一标识一个指标。

注意

指标组 torchelastic 被 torchelastic 保留用于其生成的平台级指标。例如，torchelastic 可能会将代理的重连操作的延迟（以毫秒为单位）输出为 (torchelastic, agent.rendezvous.duration.ms)。

使用指标组的一个合理方法是将它们映射到作业中的某个阶段或模块。您也可以对作业的某些高级属性进行编码，例如区域或阶段（开发 vs. 生产）。

发布指标:

使用 torchelastic 的 metrics API 类似于使用 Python 的 logging 框架。在尝试添加指标数据之前，您必须先配置一个指标处理器。

下面的示例测量了 calculate() 函数的延迟。

import time
import torch.distributed.elastic.metrics as metrics

# makes all metrics other than the one from "my_module" to go /dev/null
metrics.configure(metrics.NullMetricsHandler())
metrics.configure(metrics.ConsoleMetricsHandler(), "my_module")


def my_method():
    start = time.time()
    calculate()
    end = time.time()
    metrics.put_metric("calculate_latency", int(end - start), "my_module")

您也可以使用 `torch.distributed.elastic.metrics.prof` 装饰器来方便地、简洁地对函数进行性能分析。

# -- in module examples.foobar --

import torch.distributed.elastic.metrics as metrics

metrics.configure(metrics.ConsoleMetricsHandler(), "foobar")
metrics.configure(metrics.ConsoleMetricsHandler(), "Bar")


@metrics.prof
def foo():
    pass


class Bar:
    @metrics.prof
    def baz():
        pass

`@metrics.prof` 将发布以下指标：

<leaf_module or classname>.success - 1 if the function finished successfully
<leaf_module or classname>.failure - 1 if the function threw an exception
<leaf_module or classname>.duration.ms - function duration in milliseconds

配置 Metrics Handler:

torch.distributed.elastic.metrics.MetricHandler 负责将添加的指标值发送到特定的目的地。不同的指标组可以配置不同的指标处理器。

默认情况下，torchelastic 将所有指标发送到 /dev/null。通过添加以下配置，`torchelastic` 和 `my_app` 指标组将被打印到控制台。

import torch.distributed.elastic.metrics as metrics

metrics.configure(metrics.ConsoleMetricHandler(), group="torchelastic")
metrics.configure(metrics.ConsoleMetricHandler(), group="my_app")

编写自定义 Metric Handler:

如果您希望您的指标发送到自定义位置，请实现 torch.distributed.elastic.metrics.MetricHandler 接口，并配置您的作业使用您的自定义指标处理器。

下面是一个打印指标到 stdout 的示例：

import torch.distributed.elastic.metrics as metrics


class StdoutMetricHandler(metrics.MetricHandler):
    def emit(self, metric_data):
        ts = metric_data.timestamp
        group = metric_data.group_name
        name = metric_data.name
        value = metric_data.value
        print(f"[{ts}][{group}]: {name}={value}")


metrics.configure(StdoutMetricHandler(), group="my_app")

现在，指标组 my_app 中的所有指标都将作为以下格式打印到 stdout：

[1574213883.4182858][my_app]: my_metric=<value>
[1574213940.5237644][my_app]: my_metric=<value>

Metric Handlers

以下是 torchelastic 内置的指标处理器：

class torch.distributed.elastic.metrics.api.MetricHandler

class torch.distributed.elastic.metrics.api.ConsoleMetricHandler

class torch.distributed.elastic.metrics.api.NullMetricHandler

Methods

torch.distributed.elastic.metrics.configure(handler, group=None)

torch.distributed.elastic.metrics.prof(fn=None, group='torchelastic')

@profile 装饰器为它装饰的函数发布 duration.ms、count、success、failure 指标。

指标名称默认为函数的限定名称（class_name.def_name）。如果函数不属于一个类，它将使用叶模块名称。

用法

@metrics.prof
def x():
    pass


@metrics.prof(group="agent")
def y():
    pass

torch.distributed.elastic.metrics.put_metric(metric_name, metric_value, metric_group='torchelastic')

发布一个指标数据点。

用法

put_metric("metric_name", 1)
put_metric("metric_name", 1, "metric_group_name")