docs/designs/telemetry.md

1 # OpenBMC platform telemetry
14 The BMC on server platform gathers lots of telemetry data, which has to be
16 on telemetry over the Redfish, since it is standard API for platform
21 - OpenBMC platform telemetry shall leverage DMTF's [Redfish Telemetry Model][1]
22   for exposing platform telemetry over the network.
23 - OpenBMC platform telemetry shall leverage the [OpenBMC sensors architecture
25 - OpenBMC platform telemetry shall implement a service, called Telemetry to deal
29   architecture does not depend on it, because the Telemetry service component
35   Telemetry service requires telemetry sources to be implemented as D-Bus
40 Redfish Telemetry Model shall implement Telemetry Service with the following
46 - Metric Reports - contains actual metric reports containing telemetry data
51 OpenBMC telemetry architecture is shown on the diagram below.
55    |hwmon|        |               |Dbus sensors|   |     |Telemetry|       |
74 | | |Telemetry Service|                              |  |resources|       | | |
97 The telemetry service component is a part of Redfish and implements the DMTF's
98 [Redfish Telemetry Model][1]. Metric report definitions uses Redfish sensors
100 sensor mapping. Redfish Telemetry Service acts as presentation layer for the
101 telemetry, while Telemetry service is responsible for gathering metrics from
102 D-Bus sensors and exposing them as D-Bus objects. Telemetry service supports
115 Telemetry service supports creating and managing metric report, which may
117 Metric Report for the Redfish Telemetry Service.
123 |User|              |bmcweb|              |Telemetry|                 | D-Bus |
268 metric reports. All operations on metric reports shall be done in the Telemetry
273 In case of on demand metric report update, Telemetry service performs no
277 ### Telemetry service on [D-Bus][4]
279 Telemetry service exposes specific interfaces on D-Bus. One of them will be used
288 xyz.openbmc_project.Telemetry.ReportManager
289 /xyz/openbmc_project/Telemetry/Reports
293 [`xyz.openbmc_project.Telemetry.ReportManager`][8] for report management. The
303 [`xyz.openbmc_project.Telemetry.Report`][9] interfaces. The [`Delete`][10]
306 along with properties containing telemetry readings. Each report object contains
317 xyz.openbmc_project.Telemetry.TriggerManager
318 /xyz/openbmc_project/Telemetry/Triggers
321 The `TriggerManager` supports the `xyz.openbmc_project.Telemetry.TriggerManager`
367 | ReportPath | object path | D-Bus path to Telemetry's reading report which update shall be trigger…
375 String for created trigger - ie. '/xyz/openbmc_project/Telemetry/Triggers/{Domain}/{Name}'
379 `xyz.openbmc_project.Telemetry.Trigger` interfaces. Each trigger object contains
418 …ate metric report. This path shall point to existing reading report within the Telemetry service. |
426    the Telemetry service writes data to system journal using libjournal. The
433    +------/    +-----------+-+ |         |Telemetry|            |
458 2. For action Event, the Telemetry service shall send event using the [Redfish
461 3. For action Update, the Telemetry service will trigger the update of reading
467 ### Redfish Telemetry Service API
469 Redfish Telemetry Service shall support 2019.1 Redfish schemas for telemetry
492  |                Telemetry Service                   |  |                    |
530 Telemetry is gathering D-Bus sensors readings and exposing them in reading
531 reports over D-Bus for the Telemetry Service. Each D-Bus sensor is mapped to
534 Below examples of Redfish resources for the Telemetry Service are shown.
536 The Telemetry Service Redfish resource example:
542     "Name": "Telemetry Service",
669 MB RAM. Flash consumption by the Telemetry service is 197.5 kB. The runtime
671 single Metric Report. The runtime data is collected for the Telemetry component
673 `xyz.openbmc_project.Telemetry.Metric.OnChange` property to maximize the
681 | Telemetry service state                       | VSZ    | %VSZ | %CPU   |
712 - Telemetry service is directly compatible with Redfish Telemetry Service API,
713   which means, that Telemetry's reading reports can be directly mapped to
715 - Telemetry service unifies the way how the BMC's telemetry is exposed over the
717   add support telemetry over IPMI or any other API.
720 use collectd in cooperation with Telemetry. The one of possible configurations
725    |  D-Bus sensors  |      |   Telemetry     |
738  +---------^----------+     |    Telemetry      |
750 Telemetry service without any changes in their D-Bus interfaces. In such
751 configuration Telemetry service provides metric reports and triggers management.
753 Other possible configuration is to use collectd without the Telemetry service,
755 compatible with the Redfish. In such case, Redfish Telemetry Service won't be
762 Redfish Telemetry Service implementation as a component for the existing Redfish
776 The Telemetry's code shall be covered by the unit tests. The preferred framework
787 First step is for testing the Telemetry metric reports management. Test scenario
791 them) and bmcweb with Redfish Telemetry Service implemented. The tests shall be
819 …m/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/ReportManager.in…
821 …m/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/Report.interface…