docs/designs/telemetry.md

1 # OpenBMC platform telemetry
12 The BMC on server platform gathers lots of telemetry data, which has to be
14 on telemetry over the Redfish, since it is standard API for platform
19 - OpenBMC platform telemetry shall leverage DMTF's [Redfish Telemetry Model][1]
20   for exposing platform telemetry over the network.
21 - OpenBMC platform telemetry shall leverage the [OpenBMC sensors architecture
23 - OpenBMC platform telemetry shall implement a service, called Telemetry to deal
27   architecture does not depend on it, because the Telemetry service component
33   Telemetry service requires telemetry sources to be implemented as D-Bus
38 Redfish Telemetry Model shall implement Telemetry Service with the following
44 - Metric Reports - contains actual metric reports containing telemetry data
49 OpenBMC telemetry architecture is shown on the diagram below.
53    |hwmon|        |               |Dbus sensors|   |     |Telemetry|       |
72 | | |Telemetry Service|                              |  |resources|       | | |
95 The telemetry service component is a part of Redfish and implements the DMTF's
96 [Redfish Telemetry Model][1]. Metric report definitions uses Redfish sensors
98 sensor mapping. Redfish Telemetry Service acts as presentation layer for the
99 telemetry, while Telemetry service is responsible for gathering metrics from
100 D-Bus sensors and exposing them as D-Bus objects. Telemetry service supports
113 Telemetry service supports creating and managing metric report, which may
115 Metric Report for the Redfish Telemetry Service.
121 |User|              |bmcweb|              |Telemetry|                 | D-Bus |
266 metric reports. All operations on metric reports shall be done in the Telemetry
271 In case of on demand metric report update, Telemetry service performs no
275 **Telemetry service on [D-Bus][4]**
277 Telemetry service exposes specific interfaces on D-Bus. One of them will be used
286 xyz.openbmc_project.Telemetry.ReportManager
287 /xyz/openbmc_project/Telemetry/Reports
291 [`xyz.openbmc_project.Telemetry.ReportManager`][8] for report management. The
301 [`xyz.openbmc_project.Telemetry.Report`][9] interfaces. The [`Delete`][10]
304 along with properties containing telemetry readings. Each report object contains
315 xyz.openbmc_project.Telemetry.TriggerManager
316 /xyz/openbmc_project/Telemetry/Triggers
319 The `TriggerManager` supports the `xyz.openbmc_project.Telemetry.TriggerManager`
365 | ReportPath | object path | D-Bus path to Telemetry's reading report which update shall be trigger…
373 String for created trigger - ie. '/xyz/openbmc_project/Telemetry/Triggers/{Domain}/{Name}'
377 `xyz.openbmc_project.Telemetry.Trigger` interfaces. Each trigger object contains
416 …ate metric report. This path shall point to existing reading report within the Telemetry service. |
424    the Telemetry service writes data to system journal using libjournal. The
431 +------/    +-----------+-+ |         |Telemetry|            |
456 2. For action Event, the Telemetry service shall send event using the [Redfish
459 3. For action Update, the Telemetry service will trigger the update of reading
465 **Redfish Telemetry Service API**
467 Redfish Telemetry Service shall support 2019.1 Redfish schemas for telemetry
490  |                Telemetry Service                   |  |                    |
528 Telemetry is gathering D-Bus sensors readings and exposing them in reading
529 reports over D-Bus for the Telemetry Service. Each D-Bus sensor is mapped to
532 Below examples of Redfish resources for the Telemetry Service are shown.
534 The Telemetry Service Redfish resource example:
540     "Name": "Telemetry Service",
667 MB RAM. Flash consumption by the Telemetry service is 197.5 kB. The runtime
669 single Metric Report. The runtime data is collected for the Telemetry component
671 `xyz.openbmc_project.Telemetry.Metric.OnChange` property to maximize the
679 | Telemetry service state                       | VSZ    | %VSZ | %CPU   |
710 - Telemetry service is directly compatible with Redfish Telemetry Service API,
711   which means, that Telemetry's reading reports can be directly mapped to
713 - Telemetry service unifies the way how the BMC's telemetry is exposed over the
715   add support telemetry over IPMI or any other API.
718 use collectd in cooperation with Telemetry. The one of possible configurations
723    |  D-Bus sensors  |      |   Telemetry     |
736  +---------^----------+     |    Telemetry      |
748 Telemetry service without any changes in their D-Bus interfaces. In such
749 configuration Telemetry service provides metric reports and triggers management.
751 Other possible configuration is to use collectd without the Telemetry service,
753 compatible with the Redfish. In such case, Redfish Telemetry Service won't be
760 Redfish Telemetry Service implementation as a component for the existing Redfish
774 The Telemetry's code shall be covered by the unit tests. The preferred framework
785 First step is for testing the Telemetry metric reports management. Test scenario
789 them) and bmcweb with Redfish Telemetry Service implemented. The tests shall be
817 …m/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/ReportManager.in…
819 …m/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/Report.interface…