⚠️ 注意：有限维护

本项目不再积极维护。现有版本仍然可用，但没有计划的更新、错误修复、新功能或安全补丁。用户应注意，漏洞可能得不到解决。

TorchServe 指标 ¶

目录¶

介绍¶

TorchServe 指标大致可分为前端指标和后端指标。

前端指标：¶

API 请求状态指标
推理请求指标
系统利用率指标

注意： 系统利用率指标会定期收集（默认：每分钟一次）

后端指标：¶

默认模型指标
自定义模型指标

注意： TorchServe 提供了一个 API 来收集自定义模型指标。

默认前端和后端指标显示在默认指标部分。

指标模式¶

支持三种指标模式，即 log、prometheus 和 legacy，默认模式为 log。可以通过 config.properties 中的 metrics_mode 配置选项或 TS_METRICS_MODE 环境变量来配置指标模式。有关 config.properties 和基于环境变量的配置的更多详细信息，请参阅TorchServe 配置文档。

日志模式¶

在 log 模式下，指标会被记录到日志中，并可由指标代理进行聚合。在 log 模式下，指标默认在以下位置收集：

前端指标 - log_directory/ts_metrics.log
后端指标 - log_directory/model_metrics.log

日志文件和指标文件的位置可以在 log4j2.xml 文件中配置。

Prometheus 模式¶

在 prometheus 模式下，指标通过指标 API 端点以 Prometheus 格式提供。

旧版模式¶

legacy 模式提供与 TorchServe <= 0.7.1 版本的向后兼容性，在这种模式下：

ts_inference_requests_total、ts_inference_latency_microseconds 和 ts_queue_latency_microseconds 仅通过指标 API 端点以 Prometheus 格式提供。
前端指标记录到 log_directory/ts_metrics.log
后端指标记录到 log_directory/model_metrics.log

注意： 为了完全向后兼容 <= 0.7.1 版本，请使用旧版指标模式并启用模型指标自动检测。

入门指南¶

参考 自定义指标示例

创建自定义指标配置文件或使用默认的 metrics.yaml 文件。
在正在使用的 config.properties 中，将 metrics_config 参数设置为 yaml 文件路径
```
metrics_config=/<path>/<to>/<metrics>/<config>/<file>/metrics.yaml
```
如果未指定 metrics_config 参数，将使用默认的 metrics.yaml 配置文件。
使用 config.properties 中的 metrics_mode 配置选项或 TS_METRICS_MODE 环境变量设置您想要的指标模式。如果未设置，默认将使用 log 模式。
在处理程序 (handler) 中，如果有任何自定义指标，请使用自定义指标 API 来发出。
运行 TorchServe 并在 ts-config 标志后指定 config.properties 文件的路径

torchserve --ncs --start --model-store model_store --models my_model=model.mar --ts-config /<路径>/<到>/<配置>/<文件>/config.properties
根据选择的模式收集指标

如果是 log 模式，请检查
- 前端指标 - log_directory/ts_metrics.log
- 后端指标 - log_directory/model_metrics.log
否则，如果使用 prometheus 模式，请使用指标 API 端点。

指标配置¶

TorchServe 在 yaml 文件中定义指标配置，包括前端指标（即 ts_metrics）和后端指标（即 model_metrics）。当 TorchServe 启动时，会加载指标定义，并根据 metrics_mode 配置，将相应的指标以日志或通过指标 API 端点提供。

不支持对指标配置文件的动态更新。为了使对指标配置文件的更新生效，需要重新启动 TorchServe。

模型指标自动检测¶

默认情况下，未在指标配置文件中定义的指标不会被记录到指标日志文件中，也不会通过指标 API 端点提供。可以通过在 config.properties 中将 model_metrics_auto_detect 设置为 true 或使用 TS_MODEL_METRICS_AUTO_DETECT 环境变量来自动检测后端模型指标。默认情况下，模型指标自动检测是禁用的。

警告：使用后端指标自动检测会对性能产生影响，表现为延迟开销，通常在模型加载和给定模型的首次推理时出现。这种冷启动行为是由于新指标通常在模型加载和首次推理期间由后端发出，并由前端检测和注册。如果新指标首次更新，后续推理也可能会受到性能影响。对于经常加载/卸载多个模型的使用案例，可以通过提前在指标配置文件中指定已知指标来减轻延迟开销。

指标配置格式¶

指标配置 yaml 文件使用Prometheus 指标类型术语进行格式化。

dimensions: # dimension aliases
  - &model_name "ModelName"
  - &level "Level"

ts_metrics:  # frontend metrics
  counter:  # metric type
    - name: NameOfCounterMetric  # name of metric
      unit: ms  # unit of metric
      dimensions: [*model_name, *level]  # dimension names of metric (referenced from the above dimensions dict)
  gauge:
    - name: NameOfGaugeMetric
      unit: ms
      dimensions: [*model_name, *level]
  histogram:
    - name: NameOfHistogramMetric
      unit: ms
      dimensions: [*model_name, *level]

model_metrics:  # backend metrics
  counter:  # metric type
    - name: InferenceTimeInMS  # name of metric
      unit: ms  # unit of metric
      dimensions: [*model_name, *level]  # dimension names of metric (referenced from the above dimensions dict)
    - name: NumberOfMetrics
      unit: count
      dimensions: [*model_name]
  gauge:
    - name: GaugeModelMetricNameExample
      unit: ms
      dimensions: [*model_name, *level]
  histogram:
    - name: HistogramModelMetricNameExample
      unit: ms
      dimensions: [*model_name, *level]

注意： 在指标配置文件中添加自定义 model_metrics 时，请确保将 ModelName 和 Level 维度名称包含在维度列表的末尾，因为以下自定义指标 API 默认会包含它们：add_metric、add_counter、add_time、add_size 和 add_percent。

默认指标配置¶

默认指标在默认指标配置文件 metrics.yaml 中提供。

指标类型¶

TorchServe 指标使用与Prometheus 指标类型一致的指标类型。

指标类型是 Metric 对象的属性。用户在添加自定义指标时将受限于现有的指标类型。

class MetricTypes(enum.Enum):
    COUNTER = "counter"
    GAUGE = "gauge"
    HISTOGRAM = "histogram"

默认指标¶

默认前端指标¶

指标名称	类型	单位	维度	语义
Requests2XX	counter	计数	Level, Hostname	响应状态码在 200-300 范围内的总请求数
Requests4XX	counter	计数	Level, Hostname	响应状态码在 400-500 范围内的总请求数
Requests5XX	counter	计数	Level, Hostname	响应状态码高于 500 的总请求数
ts_inference_requests_total	counter	计数	model_name, model_version, hostname	收到的推理请求总数
ts_inference_latency_microseconds	counter	微秒	model_name, model_version, hostname	总推理延迟（微秒）
ts_queue_latency_microseconds	counter	微秒	model_name, model_version, hostname	总队列延迟（微秒）
QueueTime	gauge	毫秒	Level, Hostname	作业在请求队列中花费的时间（毫秒）
WorkerThreadTime	gauge	毫秒	Level, Hostname	worker 线程中花费的时间，不包括后端响应时间（毫秒）
WorkerLoadTime	gauge	毫秒	WorkerName, Level, Hostname	worker 加载模型所需的时间（毫秒）
CPUUtilization	gauge	百分比	Level, Hostname	主机上的 CPU 利用率
MemoryUsed	gauge	兆字节	Level, Hostname	主机上已使用的内存
MemoryAvailable	gauge	兆字节	Level, Hostname	主机上可用内存
MemoryUtilization	gauge	百分比	Level, Hostname	主机上的内存利用率
DiskUsage	gauge	千兆字节	Level, Hostname	主机上已使用的磁盘空间
DiskUtilization	gauge	百分比	Level, Hostname	主机上已使用的磁盘空间
DiskAvailable	gauge	千兆字节	Level, Hostname	主机上可用磁盘空间
GPUMemoryUtilization	gauge	百分比	Level, DeviceId, Hostname	主机上的 GPU 内存利用率，DeviceId
GPUMemoryUsed	gauge	兆字节	Level, DeviceId, Hostname	主机上已使用的 GPU 内存，DeviceId
GPUUtilization	gauge	百分比	Level, DeviceId, Hostname	主机上的 GPU 利用率，DeviceId

默认后端指标¶

指标名称	类型	单位	维度	语义
HandlerTime	gauge	ms	ModelName, Level, Hostname	后端处理程序中花费的时间
PredictionTime	gauge	ms	ModelName, Level, Hostname	后端预测时间

自定义指标 API¶

TorchServe 支持处理程序 (handler) 发出自定义指标，然后根据配置的 metrics_mode 使其可用。

带有自定义处理程序的示例，展示了自定义指标 API 的使用.

自定义处理程序 (handler) 代码提供了一个包含 metrics 对象的当前请求的上下文。

# Access metrics object in context as follows
def initialize(self, context):
    metrics = context.metrics

注意： 自定义指标 API 不应与用于以 Prometheus 格式获取指标的 HTTP API 的指标 API 端点混淆。

默认维度¶

如果未指定，指标将包含几个默认维度

模型名称 (ModelName): {name_of_model}
级别 (Level): 模型 (Model)

创建维度对象¶

指标的维度可以定义为对象。

from ts.metrics.dimension import Dimension

# Dimensions are name value pairs
dim1 = Dimension(name, value)
dim2 = Dimension(some_name, some_value)
.
.
.
dimN= Dimension(name_n, value_n)

添加通用指标¶

通用指标默认使用 COUNTER 指标类型。

添加不带默认维度的通用指标的函数 API¶

    def add_metric_to_cache(
        self,
        metric_name: str,
        unit: str,
        dimension_names: list = [],
        metric_type: MetricTypes = MetricTypes.COUNTER,
    ) -> CachingMetric:
        """
        Create a new metric and add into cache. Override existing metric if already present.

        Parameters
        ----------
        metric_name str
            Name of metric
        unit str
            unit can be one of ms, percent, count, MB, GB or a generic string
        dimension_names list
            list of dimension name strings for the metric
        metric_type MetricTypes
            Type of metric Counter, Gauge, Histogram
        Returns
        -------
        newly created Metrics object
        """

用于更新指标的 CachingMetric API

    def add_or_update(
        self,
        value: int or float,
        dimension_values: list = [],
        request_id: str = "",
):
    """
    Update metric value, request id and dimensions

    Parameters
    ----------
    value : int, float
        metric to be updated
    dimension_values : list
        list of dimension value strings
    request_id : str
        request id to be associated with the metric
    """

    def update(
        self,
        value: int or float,
        request_id: str = "",
        dimensions: list = [],
):
    """
    BACKWARDS COMPATIBILITY: Update metric value

    Parameters
    ----------
    value : int, float
        metric to be updated
    request_id : str
        request id to be associated with the metric
    dimensions : list
        list of Dimension objects
    """

# Example usage
metrics = context.metrics
# Add metric
distance_metric = metrics.add_metric_to_cache(name='DistanceInKM', unit='km', dimension_names=[...])
# Update metric
distance_metric.add_or_update(value=distance, dimension_values=[...], request_id=context.get_request_id())
# OR
distance_metric.update(value=distance, request_id=context.get_request_id(), dimensions=[...])

注意： 调用 add_metric_to_cache 不会发出指标，需要如上所示在指标对象上调用 add_or_update。

添加带默认维度的通用指标的函数 API¶

    def add_metric(
        self,
        name: str,
        value: int or float,
        unit: str,
        idx: str = None,
        dimensions: list = [],
        metric_type: MetricTypes = MetricTypes.COUNTER,
    ):
        """
        Add a generic metric
            Default metric type is counter

        Parameters
        ----------
        name : str
            metric name
        value: int or float
            value of the metric
        unit: str
            unit of metric
        idx: str
            request id to be associated with the metric
        dimensions: list
            list of Dimension objects for the metric
        metric_type MetricTypes
            Type of metric Counter, Gauge, Histogram
        """

# Example usage
metrics = context.metrics
metric = metrics.add_metric(name='DistanceInKM', value=10, unit='km', dimensions=[...])

添加基于时间的指标¶

基于时间的指标默认使用 GAUGE 指标类型。

    def add_time(self, name: str, value: int or float, idx=None, unit: str = 'ms', dimensions: list = None,
                 metric_type: MetricTypes = MetricTypes.GAUGE):
        """
        Add a time based metric like latency, default unit is 'ms'
            Default metric type is gauge

        Parameters
        ----------
        name : str
            metric name
        value: int
            value of metric
        idx: int
            request_id index in batch
        unit: str
            unit of metric,  default here is ms, s is also accepted
        dimensions: list
            list of Dimension objects for the metric
        metric_type: MetricTypes
           type for defining different operations, defaulted to gauge metric type for Time metrics
        """

注意： 默认单位是 ms。

支持的单位：['ms', 's']

# Example usage
metrics = context.metrics
metrics.add_time(name='InferenceTime', value=end_time-start_time, idx=None, unit='ms', dimensions=[...])

添加基于大小的指标¶

基于大小的指标默认使用 GAUGE 指标类型。

    def add_size(self, name: str, value: int or float, idx=None, unit: str = 'MB', dimensions: list = None,
                 metric_type: MetricTypes = MetricTypes.GAUGE):
        """
        Add a size based metric
            Default metric type is gauge

        Parameters
        ----------
        name : str
            metric name
        value: int, float
            value of metric
        idx: int
            request_id index in batch
        unit: str
            unit of metric, default here is 'MB', 'kB', 'GB' also supported
        dimensions: list
            list of Dimension objects for the metric
        metric_type: MetricTypes
           type for defining different operations, defaulted to gauge metric type for Size metrics
        """

注意： 默认单位是 MB。

支持的单位：['MB', 'kB', 'GB', 'B']

# Example usage
metrics = context.metrics
metrics.add_size(name='SizeOfImage', value=img_size, idx=None, unit='MB', dimensions=[...])

添加基于百分比的指标¶

基于百分比的指标默认使用 GAUGE 指标类型。

    def add_percent(self, name: str, value: int or float, idx=None, dimensions: list = None,
                    metric_type: MetricTypes = MetricTypes.GAUGE):
        """
        Add a percentage based metric
            Default metric type is gauge

        Parameters
        ----------
        name : str
            metric name
        value: int, float
            value of metric
        idx: int
            request_id index in batch
        dimensions: list
            list of Dimension objects for the metric
        metric_type: MetricTypes
           type for defining different operations, defaulted to gauge metric type for Percent metrics
        """

推断单位：percent

# Example usage
metrics = context.metrics
metrics.add_percent(name='MemoryUtilization', value=utilization_percent, idx=None, dimensions=[...])

添加基于计数器的指标¶

基于计数器的指标默认使用 COUNTER 指标类型。

    def add_counter(self, name: str, value: int or float, idx=None, dimensions: list = None):
        """
        Add a counter metric or increment an existing counter metric
            Default metric type is counter
        Parameters
        ----------
        name : str
            metric name
        value: int or float
            value of metric
        idx: int
            request_id index in batch
        dimensions: list
            list of Dimension objects for the metric
        """

# Example usage
metrics = context.metrics
metrics.add_counter(name='CallCount', value=call_count, idx=None, dimensions=[...])

推断单位：count

获取指标¶

用户可以从缓存中获取指标。将返回 CachingMetric 对象，用户可以访问 CachingMetric 的方法来更新指标：（例如 CachingMetric.add_or_update(value, dimension_values)、CachingMetric.update(value, dimensions)）

    def get_metric(
        self,
        metric_name: str,
        metric_type: MetricTypes = MetricTypes.COUNTER,
) -> CachingMetric:
    """
    Create a new metric and add into cache

    Parameters
    ----------
    metric_name str
        Name of metric

    metric_type MetricTypes
        Type of metric Counter, Gauge, Histogram

    Returns
    -------
    Metrics object or MetricsCacheKeyError if not found
    """

# Example usage
metrics = context.metrics
# Get metric
gauge_metric = metrics.get_metric(metric_name = "GaugeMetricName", metric_type = MetricTypes.GAUGE)
# Update metric
gauge_metric.add_or_update(value=gauge_metric_value, dimension_values=[...], request_id=context.get_request_id())
# OR
gauge_metric.update(value=gauge_metric_value, request_id=context.get_request_id(), dimensions=[...])

TorchServe 指标 ¶

目录¶

介绍¶

前端指标：¶

后端指标：¶

指标模式¶

日志模式¶

Prometheus 模式¶

旧版模式¶

入门指南¶

指标配置¶

模型指标自动检测¶

指标配置格式¶

默认指标配置¶

指标类型¶

默认指标¶

默认前端指标¶

默认后端指标¶

自定义指标 API¶

默认维度¶

创建维度对象¶

添加通用指标¶

添加不带默认维度的通用指标的函数 API¶

添加带默认维度的通用指标的函数 API¶

添加基于时间的指标¶

添加基于大小的指标¶

添加基于百分比的指标¶

添加基于计数器的指标¶

获取指标¶

文档

教程

资源

TorchServe 指标¶

目录¶

介绍¶

前端指标：¶

后端指标：¶

指标模式¶

日志模式¶

Prometheus 模式¶

旧版模式¶

入门指南¶

指标配置¶

模型指标自动检测¶

指标配置格式¶

默认指标配置¶

指标类型¶

默认指标¶

默认前端指标¶

默认后端指标¶

自定义指标 API¶

默认维度¶

创建维度对象¶

添加通用指标¶

添加不带默认维度的通用指标的函数 API¶

添加带默认维度的通用指标的函数 API¶

添加基于时间的指标¶

添加基于大小的指标¶

添加基于百分比的指标¶

添加基于计数器的指标¶

获取指标¶

文档

教程

资源

TorchServe 指标 ¶