TelemetryService特性介绍

PLUS_ONE · 2025 年3 月 1 日 09:08

介绍

最新openUBMC支持符合redfish标准的TelemetryService特性。

TelemetryService(中文称为遥测服务)主要为了满足

定期上报或记录由一组指定采集项组成的报告
针对受监控的采集项指定触发阈值，并触发对应事件或记录

两种场景，能够有效提高客户端/服务端交互的效率。

Redfish数据模型中的采集项

一个采集项是一个可度量的数量或者指标的值。采集项可以是一个环境上传感器的读值，或者一个数据计数器的值，如“传感器的读值”。

在Redfish中，可采集项作为属性分布在Redfish资源中。

可采集项在Redfish数据模型中以多种方式出现，它们可以是：

一个资源中的属性
一个资源中的一个复杂对象的属性
在一个只含有采集项的资源中

在openUBMC中，我们预置了多种采集项供用户组合。

Metrics类型

一个metric可以被它的值的表现、走向和它如何被处理的来描述。

Metric定义可以指定以下类型的metric表现：

Numeric: 值为任意实数的metric
Discrete: 值只能取特定离散值的metric, 如倾斜传感器，它测量物理实体的方位，但其值只能是垂直、水平和倾斜
Gauge: 值在一定范围内连续的metric, 大多数数字和数字计量metric都是gauge metric
Counter: 值为单调递增的非负整数的metric. 当一个counter到达它的最大值，值会置为0并继续计数
Countdown: 值为单调递减的非负整数的metric. 当一个countdown到达它的最小值，值会置为预设值并继续向下计数

Metric会被以多种方式处理，metric定义可以指定以下类型的处理方式：

Calculated: 通过对一个或多个其他metric计算来实现的metric（指定了计算方式）
Synthesized: 通过对一个或多个其他metric计算来实现的metric（未指定计算方式）
Physical sensor: 作为一个物理传感器来实现的metric

上述术语可用于更准确地定义一些常见metrics.

Environmental: 一个测量物理世界特征的metric, 如温度。Environmental metric被实现为physical sensor, calculated或者synthesized
- 对于physical sensor, 需要知道真实的物理值和测量值是有区别的。对于一个physical sensor，metric定义可以指定精度、准确度和误差特性
- 对于calculation metric, calculated metric的误差特性可以根据输入metrics的误差特性计算得出，这被称为误差传播
Digital meter: 用于获取数字仪表读数的numeric metric, 如cache命中寄存器的读数
Statistical: 在一个时间间隔中计算得到的calculated metric, 如最大功耗

telemetry模型

Telemetry模型被设计为一组可选功能。这些功能是相互独立的。Redfish服务可以实现telemetry模型中的一项、两项或更全功能。例如，metric定义可以在没有实现triggers的情况下提供。对于每一个metric property, 可以决定是否提供其metric定义。

telemetry服务

如果提供了Redfish服务，需要在service root包含TelemetryService属性。

TelemetryService资源是service root最上层的可见资源。TelemetryService有一系列从属于它的资源集合：MetricDefinition资源集合、MetricReportDefinition资源集合、MetricReport资源集合和Triggers资源集合。

MetricDefinition资源包含metric properties的特征或元数据。

MetricReportDefinition资源包含了生成metric report的描述符，MetricReport资源则是从对应MetricReportDefinition生成的报告。

MetricDefinition

MetricDefinition包含指向该定义所应用的metric properties的链接。

alt text

在该数据模型中，Power资源包含了一个PowerConsumedWatts属性，描述PowerConsumedWattsmetric property的metric definition是metric definition集合的一个成员。这个metric definition被命名为PowerconsumedWatts来更容易地将metric property和它的definition联系起来。

Metric definition包含了该definition使用的任何property的引用，即允许相同的metric definition用于描述多个metric properties. 例如，PowerConsumedWattsmetric definition可以引用Chassis集合中每一个Power资源下的PowerConsumedWatts属性。

在metric definition中，属性可以分为四类：context, usage, measurement和metric references.

context

context类提供以下属性：

Property	Description	Values
MetricType	metric的类型	Numeric Discrete Gauge Counter
Implementation	获取metric的方式	PhysicalSensor DigitalMeter Calculated Synthesized
PhysicalContext	metric的物理上下文	See the PhysicalContext schema.

usage

usage类提供客户端如何使用metric的指导：

Property	Description	Values
Calculable	可用于metric读数的计算类型	NonCalculatable: 没有可以被用于这个metric读数的计算 Summable: 多个实例的metric读数之和可以累加 NonSummable: 多个实例的metric读数之和累加无意义
Calibration	客户端添加到metric读数的度量偏移，以获取到实际值	一个十进制值
IsLinear	判断metric读数是否是线性的，线性的metrics可以用大于、小于关系比较	boolean
MaxReadingRange	metric读数的最大的可能值	一个十进制值
MetricDataType	metric读数的数据类型	Boolean String Decimal Integer String Enumeration: 一组定义的枚举字符串
MinReadingRange	metric读数的最小的可能值	一个十进制值

measurement

measurement类提供的是表征measurement本身特性（来自 Energy Efficient HPC WG’s PowerAPI 标准）：

Property	Description
Accuracy	测量值与实际值的估计+/-百分比误差
Precision	值中的有效位数
TimestampAccuracy	返回时间戳的准确性，以 ISO8601 duration表示。

以下是Redfish telemetry模型定义的其它属性：

Property	Description
CalculationAlgorithm	为获得metric执行的计算
CalculationTimeInterval	对metric读数进行计算的时间间隔
DiscreteValues	离散metric的可能值
SensingInterval	更新metric的时间间隔
Units	metric单位，由UCUM定义

metric references

MetricDefinition资源包含了一个metric definition适用的所有metric properties引用的list. 一个metric definition可能适用于很多metric properties, 这可能导致MetricProperties属性包含一个非常大的引用每一个metric property的list.

为了减小这个list的大小，可以用通配符Wildcards搭配MetricProperties一起使用。通配符机制也可以用于MetricReportDefinition和Triggers资源。

MetricProperties

MetricProperties属性的键值是一个包含metric definition可以描述的任意metric property的list, 键值元素字符串中可能包含通配符，通配符用大括号括起来。

{
    "MetricProperties": [
        "/redfish/v1/Chassis/{ChassisID}/Power#/PowerControl/0/PowerConsumedWatts",
        "/redfish/v1/Chassis/{ChassisID}/Power#/PowerControl/1/PowerConsumedWatts"
    ]
}

Wildcards

Wildcards属性的键值是一个通配符替换列表的list, 每个通配符条目包含MetricProperties中使用的通配符以及用于替换的值。*表示所有可能取值。

下例表示每个MetricProperties键值元素中的字符串ChassisID可以替换为1、2和3.

{
    "Wildcards": [
        {
            "Name": "ChassisID",
            "Values": [
                "1",
                "2",
                "3"
            ]
        }
    ]
}

MetricDefinition例子

下面的例子包含了Power资源下的PowerConsumedWatts属性的metric definition.

Power资源包含了一个array类型的PowerControl属性，array中每一个元素都包含一个PowerConsumedWatts属性，metric definition中的MetricProperties属性指向了两个从Power资源获取的PowerConsumedWatts属性。

{
    "@odata.id": "/redfish/v1/TelemetryService/MetricDefinitions/PowerConsumedWatts",
    "@odata.type": "#MetricDefinition.v1_0_3.MetricDefinition",
    "Id": "PowerConsumedWatts",
    "Name": "Power Consumed Watts Metric Definition",
    "MetricType": "Numeric",
    "Implementation": "PhysicalSensor",
    "PhysicalContext": "PowerSupply",
    "MetricDataType": "Decimal",
    "Units": "W",
    "Precision": 4,
    "Accuracy": 1,
    "Calibration": 2,
    "MinReadingRange": 0,
    "MaxReadingRange": 50,
    "SensingInterval": "PT1S",
    "TimestampAccuracy": "PT1S",
    "Wildcards": [
        {
            "Name": "ChassisID",
            "Values": [
                "1",
                "2",
                "3"
            ]
        }
    ],
    "MetricProperties": [
        "/redfish/v1/Chassis/{ChassisID}/Power#/PowerControl/0/PowerConsumedWatts",
        "/redfish/v1/Chassis/{ChassisID}/Power#/PowerControl/1/PowerConsumedWatts"
    ]
}

MetricReportDefinition

被Redfish服务创建的metric report可以用Redfish event服务传输上报，或者被存储在本地用于检索，或者都支持。Metric report根据读数变化或者上报请求周期性地创建，常见用于聚合metric读数。

与MetricDefinition类似，MetricReportDefinition资源定义了metric report的内容和周期性，也包含这个定义适用的metric properties.

alt text

在MetricReportDefinition资源下，属性可以被分为四类：context, when to generate, disposition和metric references.

context

context类提供以下属性：

Property	Description	Values
MetricReportDefinitionType	metric report创建的方式	Periodic: 周期性生成 OnChange: metric值变化时生成 OnRequest: 用户侧发送GET请求时生成
MetricReportDefinitionEnabled	是否允许对应metric report生成	boolean

when to generate

当MetricReportDefinitionType为Periodic时，对应Schedule指定生成metric report的时间。Schedule下RecurrenceInterval属性决定了生成metric report的频率，其它属性则控制metric report生成的其它方面。

下面的例子指定metric report每60s生成一次，100次后停止。

{
    "MetricReportDefinitionType": "Periodic",
    "Schedule": {
        "RecurrenceInterval": "PT60S",
        "MaxOccurrences": 100
    },
    ...
}

disposition

下面的属性定义了服务对matric值进行的操作：

Property	Description	Values
ReportActions	指定当metric report生成时对其进行的操作	LogToMetricReportsCollection: metric report生成时，将其记录到metric report集合中 RedfishEvent: metric report生成时，发送`MetricReport`类型的Redfish事件消息
ReportUpdates	指定当metric report已经存在时如何操作后续报告	Overwrite: 以更新过的报告覆盖之前的报告 AppendWrapsWhenFull: 当metric report更新时，将新的信息附加到报告中，达到最大容量后开始覆盖 AppendStopsWhenFull: 当metric report更新时，将新的信息附加到报告中，达到最大容量就停止 NewReport: 当metric report更新时，创建一个新的metric report, 资源名为metric report资源名加时间戳
CalculationAlgorithm	指定适用于metric properties list的函数	Average: metric是这个metric一段时间的读数的平均值 Maximum: metric是这个metric一段时间的读数的最大值 Minimum: metric是这个metric一段时间的读数的最小值 Summation: metric是这个metric一段时间的读数的和
CollectionTimeScope	指定收集metric值的时间范围	Point: metric值适用于`Timestamp`属性指定的时间点 Interval: metric值适用于`Timestamp`和`CollectionDuration`属性决定的一段时间 StartupInterval: metric值适用于开始测量起的一个时间间隔后（存疑，原文为The metric values to a time interval that began at the startup of the measured resource.）

metric references

MetricReportDefinition资源包含了一个引用Redfish数据模型包含的metric properties或可以被运算的metric property的列表，因此，MetricProperties属性可能作为一个属性出现，也可能作为一个Metrics属性中的属性。对于这些用法，通配符机制都适用。

MetricProperties

MetricProperties为array类型，以指向包含在metric report中的metrics为元素，可能含有通配符。

下面的JSON片段指向了两个机架实例Tray_1和Tray_2的PowerControl属性的第0项中的AverageConsumedWatts属性。

{
    "Wildcards": [
        {
            "Name": "PWild",
            "Values": [
                "0"
            ]
        },
        {
            "Name": "TWild",
            "Values": [
                "Tray_1",
                "Tray_2"
            ]
        }
    ],
    "MetricProperties": [
        "/redfish/v1/Chassis/{TWild}/Power#/PowerControl/{PWild}/PowerConsumedWatts/PowerMetrics/AverageConsumedWatts"
    ]
}

Metrics

尽管上面的例子可以用于引用关注的Redfish模型中的属性，但还有相当一部分场景需要用到无法直接获取的属性。为覆盖这些情况，Metrics属性可以用于指向对metric property进行的运算，实现定义不存在于Redfish数据模型的数据。

Metrics属性用于指定metric report中包含的metrics, 这些metrics是通过将指定的算法运算到每一个列出的metric properties上得到的。Metrics属性是一个包含了以下属性的对象数组：

Property	Description
MetricId	metric的标签
MetricProperties	用于执行计算的metric properties的URI列表
CollectionFunction	对列表中每个metric properties执行的函数
CollectionDuration	函数执行的时间间隔
CollectionTimeScope	函数适用的时间范围

以下JSON片段定义了用PowerConsumedWatts属性第0项的PowerControl属性计算1s时间间隔的平均值。

{
    "Wildcards": [
        {
            "Name": "PWild",
            "Values": [
                "0"
            ]
        },
        {
            "Name": "TWild",
            "Values": [
                "Tray_1",
                "Tray_2"
            ]
        }
    ],
    "Metrics": [
        {
            "MetricId": "AverageConsumeWatts",
            "CollectionFunction": "Average",
            "CollectionTimeScope": "Interval",
            "CollectionDuration": "PT1S",
            "MetricProperties": [
                "/redfish/v1/Chassis/{TWild}/Power#/PowerControl/{PWild}/PowerConsumedWatts"
            ]
        }
    ]
}

MetricReportDefinition例子

Power数据

{
    "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/PowerMetrics",
    "@odata.type": "#MetricReportDefinition.v1_3_0.MetricReportDefinition",
    "Id": "PowerMetrics",
    "Name": "Transmit and Log Power Metrics",
    "MetricReportDefinitionType": "Periodic",
    "MetricReportDefinitionEnabled": true,
    "Schedule": {
        "RecurrenceInterval": "PT0.1S"
    },
    "ReportActions": [
        "RedfishEvent",
        "LogToMetricReportsCollection"
    ],
    "ReportUpdates": "Overwrite",
    "MetricReport": {
        "@odata.id": "/redfish/v1/TelemetryService/MetricReports/PowerMetrics"
    },
    "Status": {
        "State": "Enabled"
    },
    "Wildcards": [
        {
            "Name": "PWild",
            "Values": [
                "0",
                "1"
            ]
        },
        {
            "Name": "TWild",
            "Values": [
                "Tray_1",
                "Tray_2",
                "Tray_3"
            ]
        }
    ],
    "MetricProperties": [
        "/redfish/v1/Chassis/{TWild}/Power#/PowerControl/{PWild}/PowerMetrics/AverageConsumedWatts",
        "/redfish/v1/Chassis/{TWild}/Power#/PowerControl/{PWild}/PowerMetrics/MinConsumedWatts",
        "/redfish/v1/Chassis/{TWild}/Power#/PowerControl/{PWild}/PowerMetrics/MaxConsumedWatts"
    ]
}

Power使用率

{
    "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/PlatformPowerUsage",
    "@odata.type": "#MetricReportDefinition.v1_3_0.MetricReportDefinition",
    "Id": "PlatformPowerUsage",
    "Name": "Transmit and Log Platform Power Usage",
    "MetricReportDefinitionType": "Periodic",
    "MetricReportDefinitionEnabled": true,
    "Schedule": {
        "RecurrenceInterval": "PT1H"
    },
    "ReportActions": [
        "RedfishEvent",
        "LogToMetricReportsCollection"
    ],
    "ReportUpdates": "AppendWrapsWhenFull",
    "AppendLimit": 256,
    "MetricReport": {
        "@odata.id": "/redfish/v1/TelemetryService/MetricReports/PlatformPowerUsage"
    },
    "Status": {
        "State": "Enabled"
    },
    "Wildcards": [
        {
            "Name": "PWild",
            "Values": [
                "0"
            ]
        },
        {
            "Name": "TWild",
            "Values": [
                "Tray_1",
                "Tray_2"
            ]
        }
    ],
    "MetricProperties": [
        "/redfish/v1/Chassis/{TWild}/Power#/PowerControl/{PWild}/PowerConsumedWatts"
    ]
}

MetricReport

由MetricReportschema定义的metric reports包含了metric读数和与这些数据相关联的元数据。根据相应的metric report definition配置，metric report可以在telemetry service下的metric report集合资源中，也可以异步地作为事件上报。

以下属性可以在metric report中出现：

Property	Description
MetricReportDefinition	指向生成这个metric report的metric report definition
MetricValues	捕获到的metric读数的对象数组
Timestamp	metric report创建的日期和时间，这不一定是对metric读数本身采样时的时间

MetricValues数组包含与metric report definition相关的已被捕获的读数列表，根据metric report definition的配置，metric report可以包含历史数据。下面的属性可以用在MetricValue数组的数据中：

Property	Description
MetricId	metric的标签
MetricValue	metric读数的字符串表示。必须注意，即使是boolean和number也需要编码为字符串，也就是说客户端需要根据metric definition解码
Timestamp	metric被服务采样的日期和时间存疑：与上面的定义说明不太符合
MetricProperty	派生此metric的属性对应的URI
MetricDefinition	指向metric definition的链接，提供metric property的特征

MetricReport例子

Power使用率

{
    "@odata.id": "/redfish/v1/TelemetryService/MetricReports/PlatformPowerUsage",
    "@odata.type": "#MetricReport.v1_3_0.MetricReport",
    "Id": "PlatformPowerUsage",
    "Name": "PlatformPowerUsage",
    "MetricReportDefinition": {
        "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/PlatformPowerUsage"
    },
    "MetricValues": [
        {
            "Timestamp": "2016-11-08T12:25:00-05:00",
            "MetricValue": "103",
            "MetricProperty": "/redfish/v1/Chassis/Tray_1/Power#/PowerControl/0/PlatformConsumedWatts"
        },
        {
            "Timestamp": "2016-11-08T12:25:00-05:00",
            "MetricValue": "103",
            "MetricProperty": "/redfish/v1/Chassis/Tray_2/Power#/PowerControl/0/PlatformConsumedWatts"
        },
        {
            "Timestamp": "2016-11-08T13:25:00-05:00",
            "MetricValue": "106",
            "MetricProperty": "/redfish/v1/Chassis/Tray_1/Power#/PowerControl/0/PlatformConsumedWatts"
        },
        {
            "Timestamp": "2016-11-08T13:25:00-05:00",
            "MetricValue": "106",
            "MetricProperty": "/redfish/v1/Chassis/Tray_2/Power#/PowerControl/0/PlatformConsumedWatts"
        },
        {
            "Timestamp": "2016-11-08T14:25:00-05:00",
            "MetricValue": "107",
            "MetricProperty": "/redfish/v1/Chassis/Tray_1/Power#/PowerControl/0/PlatformConsumedWatts"
        },
        {
            "Timestamp": "2016-11-08T14:25:00-05:00",
            "MetricValue": "107",
            "MetricProperty": "/redfish/v1/Chassis/Tray_2/Power#/PowerControl/0/PlatformConsumedWatts"
        }
    ]
}

Triggers

Triggers资源指定了适用于列出的metrics的触发门限，可以触发一个或多个action, 如通过事件上报传输或者以log形式存储。

Triggers资源允许用一组通用的触发器应用于多个metric properties，以消除客户端对各种资源使用触发门限的差异。

alt text

通用属性

以下属性通常用于所有Triggers资源：

Property	Description	Values
MetricType	受监测的metrics类型	Numeric Discrete
TriggerActions	触发器条件满足时进行的操作	LogToLogService: 用日志服务记录触发器条件 RedfishEvent: 作为Redfish事件上报给订阅 RedfishMetricReport: 强制更新指定metric reports
MetricProperties	受触发器监测的metrics	由Redfish数据模型对应URIs组成的字符串数组，可以使用通配符

Numberic触发器

MetricType为Numberic时配套使用NumericThresholds属性用于指定数字类型的触发器，会包含以下属性：

Property	Description
UpperWarning	超过正常范围的读数值
UpperCritical	超过正常范围且需要注意的读数值
LowerWarning	低于正常范围的读数值
LowerCritical	低于正常范围且需要注意的读数值

上述每一个门限属性都是对象，且包含以下属性：

Property	Description
Reading	门限值
Activation	触发触发器的门限方向
DwellTime	必须超过门限触发值的持续时间

Discrete触发器

MetricType为Discrete时配套使用DiscreteTriggerConditions和DiscreteTriggers属性用于指定离散型触发器。

DiscreteTriggerConditions属性指定触发器出现的条件，可以包含以下值：

Specified: 当metric值为DiscreteTriggers属性中列出的值时触发触发器
Changes: 当metric值改变时触发触发器

如果DiscreteTriggerCondition包含了Specified值，DiscreteTriggers属性就是一个定义了会触发触发器的metric取值的数组。DiscreteTriggers是一个包含了以下属性的数组：

Property	Description
Name	触发器命名
Value	构造触发事件的离散型metric取值
DwellTime	触发器触发前单个触发事件的持续事件
Severity	对应Redfish上报事件`Severity`属性取值

话题		回复	浏览量
关于redfish接口TelemetryService的实现交流互助区提问求助	11	180	2026 年4 月 11 日
温度采集不满足10分钟循环覆盖交流互助区提问求助	8	68	2026 年6 月 17 日
MetricProperties下面是否可以配置不同器件属性交流互助区提问求助	5	65	2026 年6 月 12 日
【已评审】支持度量、追踪、日志采集策略配置 Interface评审	4	190	2025 年8 月 4 日
【已评审】支持PowerSupplyMetrics接口新标准 Interface评审	10	141	2025 年12 月 16 日

TelemetryService特性介绍

介绍

Redfish数据模型中的采集项

Metrics类型

telemetry模型

telemetry服务

MetricDefinition

context

usage

measurement

metric references

MetricProperties

Wildcards

MetricDefinition例子

MetricReportDefinition

context

when to generate

disposition

metric references

MetricProperties

Metrics

MetricReportDefinition例子

Power数据

Power使用率

MetricReport

MetricReport例子

Power使用率

Triggers

通用属性

Numberic触发器

Discrete触发器

相关话题