Update Telemetry service interfaces
This change updates description of interfaces utilized by Telemetry
service, so that its contents mirror the desired implementation.
Change-Id: I7207c4889912e848a058279b9d89f643a7e0b6b8
Signed-off-by: Michal Orzel <michalx.orzel@intel.com>
diff --git a/yaml/xyz/openbmc_project/Telemetry/Report.interface.yaml b/yaml/xyz/openbmc_project/Telemetry/Report.interface.yaml
index 041f582..e074da6 100644
--- a/yaml/xyz/openbmc_project/Telemetry/Report.interface.yaml
+++ b/yaml/xyz/openbmc_project/Telemetry/Report.interface.yaml
@@ -17,37 +17,27 @@
Defines if the report configuration is stored in non volatile memory.
Configuration contains all Report properties excluding Readings.
- name: ReadingParameters
- type: array[struct[array[object_path],enum[self.OperationType],string,string,enum[self.CollectionTimescope],uint64]]
+ type: array[struct[array[struct[object_path,string]],enum[self.OperationType],string,enum[self.CollectionTimescope],uint64]]
description: >
- Array of structures that contains array of sensor paths that are
- monitored by Telemetry service, operation type, metric Id, metadata,
- collection timescope and collection duration. Metric Id and metadata are
- used to store user details, e.g. metadata can be used to map sensor name
- to DBus path.
+ Collection of metric parameters. Single entry consists of:
+ array of [sensor path, metadata] tuples, operation type, metric ID,
+ collection timescope and collection duration. Sensor paths point to
+ sensors providing readings. Metadata contains client information; in
+ case of Redfish it shall be metric's URI. Operation type provides
+ knowledge of action executed on readings. Metric ID contains name that
+ can be mapped to metadata (like Redfish Metric ID). Collection
+ timescope specifies type of time scope applied to specific metric.
+ Collection duration stores timestamp related with timescope type in
+ milliseconds.
- name: Readings
type: struct[uint64,array[struct[string,string,double,uint64]]]
description: >
- Structure that contains timestamp of readings update in milliseconds and
- array of metric Id, metadata, reading value and timestamp of single
- reading update in milliseconds. Metric Id and metadata are equal to its
- counterparts in ReadingParameters property.
+ Structure that contains timestamp of readings update in milliseconds
+ and array of metric Id, metadata, reading value and timestamp of
+ single reading update in milliseconds. Metric Id and metadata are
+ equal to its counterparts in ReadingParameters property.
flags:
- readonly
- - name: EmitsReadingsUpdate
- type: boolean
- description: >
- On Readings update PropertiesChanged signal is emitted. It allows to
- decrease generation of load on DBus when Readings property is updated.
- Redfish Event Service requires this option to be equal to true.
- flags:
- - const
- - name: LogToMetricReportsCollection
- type: boolean
- description: >
- Presence of Report in Metric Report Collection in Redfish Telemetry
- Service.
- flags:
- - const
- name: ReportingType
type: enum[self.ReportingType]
description: Defines how readings are updated.
@@ -67,23 +57,51 @@
type: boolean
description: >
Indicates if readings in report will be updated. This may be set to
- false by the service if ReportUpdates property is 'AppendStopsWhenFull'
- and readings limit specified by AppendLimit is reached.
+ false by the service if ReportUpdates property is
+ 'AppendStopsWhenFull' and readings limit specified by AppendLimit is
+ reached.
+ - name: ErrorMesages
+ type: array[struct[enum[self.ErrorType],string]]
+ description: >
+ Stores errors related with incorrect or conflicting property values.
+ Error messages are stored in pairs containing error type and affected
+ property.
+ flags:
+ - readonly
+ - name: Name
+ type: string
+ description: >
+ Defines the name of reading report to be exposed over D-Bus.
+ flags:
+ - const
+ - name: ReportActions
+ type: array[enum[self.ReportActions]]
+ description: >
+ Contains set of flags indicating additional actions that can be
+ triggered after readings' update.
+ - name: Triggers
+ type: array[object_path]
+ description: >
+ Array of paths to Trigger objects associated with this report.
+ flags:
+ - readonly
enumerations:
- name: OperationType
description: Type of action that is executed on readings.
values:
- - name: Single
- description: Store the latest reading.
- - name: Max
- description: Store maximal reading during defined time period.
- - name: Min
- description: Store minimal reading during defined time period.
- - name: Avg
- description: Calculate average of readings during defined time period.
- - name: Sum
- description: Calculate sum of readings over defined time period.
+ - name: Maximum
+ description: >
+ Store maximal reading during defined time period.
+ - name: Minimum
+ description: >
+ Store minimal reading during defined time period.
+ - name: Average
+ description: >
+ Calculate average of readings during defined time period.
+ - name: Summation
+ description: >
+ Calculate sum of readings over defined time period.
- name: ReportingType
description: >
The type that defines when Readings are updated.
@@ -103,21 +121,17 @@
values:
- name: Overwrite
description: >
- Last sensor reading is written to Readings overwriting the previous
- value. AppendLimit set by user is ignored. Readings size is equal to
- count of all sensors across all metrics.
+ Last sensor reading is written to Readings overwriting the
+ previous value. AppendLimit set by user is ignored. Readings
+ size is equal to count of all sensors across all metrics.
- name: AppendWrapsWhenFull
description: >
- Append sensor reading to Readings up to limit specify in AppendLimit
- then start from the beginning.
+ Append sensor reading to Readings up to limit specify in
+ AppendLimit then start from the beginning.
- name: AppendStopsWhenFull
description: >
- Append sensor reading to Readings up to limit specify in AppendLimit
- then stop till report update.
- - name: NewReport
- description: >
- A new report is created, whose name is the current metric report name
- concatenated with the timestamp.
+ Append sensor reading to Readings up to limit specify in
+ AppendLimit then stop till report update.
- name: CollectionTimescope
description: >
The time scope of the related metric values.
@@ -129,12 +143,39 @@
- name: Interval
description: >
The corresponding metric apply to a time interval. The reading
- timestamp in Readings property specifies the end of the time interval
- and the collection duration of ReadingParameters specify its duration.
+ timestamp in Readings property specifies the end of the time
+ interval and the collection duration of ReadingParameters
+ specify its duration.
- name: StartupInterval
description: >
The corresponding metric apply to a time interval that began on
- report creation. The reading timestamp in Readings property specifies
- the end of the time interval. Collection duration of
+ report creation. The reading timestamp in Readings property
+ specifies the end of the time interval. Collection duration of
ReadingParameters specifies the duration between the startup of
resource and timestamp.
+ - name: ErrorType
+ description: >
+ Enumerates error types that might occur during properties'
+ configuration.
+ values:
+ - name: PropertyConflict
+ description: >
+ Appears in situation when two properties, which are dependent
+ from each other, have conflicting values. For example, when
+ ReportingType property has value "Periodic", but Interval is set
+ to 0, such conflict will occur.
+ - name: ReportActions
+ description: >
+ Enumerates types of actions, that can be triggered when Readings
+ property value is updated.
+ values:
+ - name: EmitsReadingsUpdate
+ description: >
+ On Readings update PropertiesChanged signal is emitted. It
+ allows to decrease generation of load on DBus when Readings
+ property is updated. Redfish Event Service requires this option
+ to be equal to enabled.
+ - name: LogToMetricReportsCollection
+ description: >
+ On Readings update report is stored to Metric Report Collection
+ in Redfish Telemetry Service.
diff --git a/yaml/xyz/openbmc_project/Telemetry/ReportManager.interface.yaml b/yaml/xyz/openbmc_project/Telemetry/ReportManager.interface.yaml
index ae8d36f..6f596e2 100644
--- a/yaml/xyz/openbmc_project/Telemetry/ReportManager.interface.yaml
+++ b/yaml/xyz/openbmc_project/Telemetry/ReportManager.interface.yaml
@@ -5,54 +5,65 @@
methods:
- name: AddReport
description: >
- Create new object that represent Report with
+ Create new object that represents Report with
xyz.openbmc_project.Telemetry.Report interface stored in path
- /xyz/openbmc_project/Telemetry/Reports/{Domain}/{Name} where
- Domain and Name are parameters of this method.
+ /xyz/openbmc_project/Telemetry/Reports/{properties[Id]} where
+ properties[Id] is passed into this method as a parameter.
parameters:
- - name: name
- type: string
+ - name: properties
+ type: array[dict[string,variant[boolean,uint32,uint64,string,enum[xyz.openbmc_project.Telemetry.Report.ReportingType],enum[xyz.openbmc_project.Telemetry.Report.ReportUpdates],array[enum[xyz.openbmc_project.Telemetry.Report.ReportActions]],array[struct[array[struct[object_path,string]],enum[xyz.openbmc_project.Telemetry.Report.OperationType],string,enum[xyz.openbmc_project.Telemetry.Report.CollectionTimescope],uint64]]]]]
description: >
- Defines the name of report to be exposed over D-Bus. Service allows
- to use separator '/' in name to group reports in directory.
- - name: reportingType
- type: enum[xyz.openbmc_project.Telemetry.Report.ReportingType]
- description: Defines report type
- - name: reportUpdates
- type: enum[xyz.openbmc_project.Telemetry.Report.ReportUpdates]
- description: Defines report update type
- - name: appendLimit
- type: size
- description: >
- Defines the maximum number of entries in 'Readings' property.
- - name: emitsReadingsUpdate
- type: boolean
- description: >
- Defines presence of PropertiesChanged signal for
- xyz.openbmc_project.Telmetry.Report.Readings property.
- - name: logToMetricReportsCollection
- type: boolean
- description: >
- Defines presence of Report in Metric Report Collection in Redfish
- Telemetry Service.
- - name: interval
- type: uint64
- description: >
- Defines period of time in milliseconds when Report is updated with
- new readings. Minimal interval is defined in MinInterval property.
- - name: metricParams
- type: array[struct[array[object_path],enum[xyz.openbmc_project.Telemetry.Report.OperationType],string,string,enum[xyz.openbmc_project.Telemetry.Report.CollectionTimescope],uint64]]
- description: >
- Array of metric parameters where first parameter is an array of DBus
- sensor paths. Second parameter specifies operation type. Third is a
- metric Id and fourth is a metadata, both are used to store user
- details. Fifth and sixth are used for collection timescope and
- collection duration.
+ Map of properties defining added report object. Key is the
+ string identifier of property. Value is a variant, whose
+ underlying type is dependent from the key. Possible key values
+ are: Id, Name, ReportingType, ReportActions, Interval,
+ AppendLimit, ReportUpdates, MetricParams, Enabled. All keys are
+ optional, therefore it is acceptable to pass an empty map here.
+
+ Id (string) - unique identifier of created Report object to be
+ exposed over D-Bus. Acceptable formats are: "{Id}",
+ "{Prefix}/{SubId}", "{Prefix}/". If the last variant is used,
+ service will generate unique SubId value by itself.
+
+ Name (string) - user friendly name of created Report object.
+
+ ReportingType (enum[
+ xyz.openbmc_project.Telemetry.Report.ReportingType]) - indicates
+ when readings should be updated. Possible values are listed in
+ Report interface documentation.
+
+ ReportActions (array[enum[
+ xyz.openbmc_project.Telemetry.Report.ReportActions]]) - possible
+ additional actions to trigger after readings' update, as
+ specified in Report interface documentation.
+
+ Interval (uint64) - period of time in milliseconds when Report
+ is updated with new readings. Minimal interval is defined in
+ MinInterval property.
+
+ AppendLimit (size) - maximum number of entries in 'Readings'
+ property.
+
+ ReportUpdates (enum[
+ xyz.openbmc_project.Telemetry.Report.ReportUpdates]) - indicates
+ how readings should be updated. Possible values are listed in
+ Report interface documentation.
+
+ MetricParams (array[struct[array[struct[object_path,string]],
+ enum[xyz.openbmc_project.Telemetry.Report.OperationType],string,
+ enum[xyz.openbmc_project.Telemetry.Report.CollectionTimescope],
+ uint64]]) - array of metric parameters, which are stored in a
+ way specified in description of ReadingParameters property from
+ Report interface documentation.
+
+ Enabled (boolean) - indicates if readings in report will be
+ updated.
returns:
- name: reportPath
type: object_path
description: >
- Path to new report -> /xyz/openbmc_project/Telemetry/Reports/{name}.
+ Path to new report ->
+ /xyz/openbmc_project/Telemetry/Reports/{parameters[Id]}.
properties:
- name: MaxReports
@@ -71,3 +82,10 @@
interval parameter in AddReport method.
flags:
- const
+ - name: SupportedOperationTypes
+ type: array[enum[xyz.openbmc_project.Telemetry.Report.OperationType]]
+ description: >
+ Contains subset of operation types currently supported by this
+ service.
+ flags:
+ - const
diff --git a/yaml/xyz/openbmc_project/Telemetry/Trigger.interface.yaml b/yaml/xyz/openbmc_project/Telemetry/Trigger.interface.yaml
index b9984ff..747c349 100644
--- a/yaml/xyz/openbmc_project/Telemetry/Trigger.interface.yaml
+++ b/yaml/xyz/openbmc_project/Telemetry/Trigger.interface.yaml
@@ -20,40 +20,45 @@
- name: Persistent
type: boolean
description: Defines if Trigger is stored in non volatile memory.
- - name: ReportNames
- type: array[string]
+ - name: Reports
+ type: array[object_path]
description: >
- Collection of report names that are updated when threshold conditions
- are met. List is ignored if TriggerActions property does not contain
- 'UpdateReport' action.
+ Collection of Report objects that are updated when threshold
+ conditions are met. List is ignored if TriggerActions property does
+ not contain 'UpdateReport' action.
- name: Sensors
- type: array[struct[object_path, string]]
+ type: array[dict[object_path,string]]
description: >
- Array of sensors that is monitored within trigger. First parameter of a
- structure is a sensor path. Second parameter is a metadata that is used
- to store user data about sensor.
+ Map of sensors that is monitored within trigger. D-Bus sensor path is
+ used as map's key. Its value is a metadata that is used
+ to store user data about sensor. In Redfish, metadata will be set to
+ endpoint corresponding to that sensor.
- name: Thresholds
type: variant[array[struct[enum[self.Type],uint64,enum[self.Direction],double]],array[struct[string,enum[self.Severity],uint64,string]]]
description: >
First type in variant is a collection of numeric thresholds that has
following fields - type, dwell time, direction and threshold value.
- Second type holds by variant is a collection of discrete thresholds that
- contains following fields - user id, severity, dwell time and threshold
- value. Discrete value does not need to be a number. Numeric threshold
- array is limited by Type enumeration, only 4 elements are allowed.
- Discrete threshold array size is not limited. If discrete threshold
- array is empty than every value change is taken into account of
- threshold condition. Dwell time specify for how long condition has to
- persist to trigger an action.
+ Second type holded by variant is a collection of discrete thresholds
+ that contains following fields - user id, severity, dwell time and
+ threshold value. Discrete value does not need to be a number. Numeric
+ threshold array is limited by Type enumeration, only 4 elements are
+ allowed. Discrete threshold array size is not limited. If discrete
+ threshold array is empty then every value change is taken into account
+ of threshold condition. Dwell time specifies for how long condition
+ has to persist to trigger an action.
+ - name: Name
+ type: string
+ description: >
+ Defines the name of trigger to be exposed over D-Bus.
enumerations:
- name: TriggerAction
description: >
Defines a action which is taken once threshold condition is met.
values:
- - name: LogToLogService
+ - name: LogToJournal
description: Trigger will log to journal.
- - name: RedfishEvent
+ - name: LogToRedfishEventLog
description: Trigger will log Redfish message.
- name: UpdateReport
description: >
@@ -70,16 +75,17 @@
- name: UpperCritical
- name: Direction
description: >
- Defines in which direction threshold value is crossed to fulfill numeric
- threshold condition.
+ Defines in which direction threshold value is crossed to fulfill
+ numeric threshold condition.
values:
- name: Either
description: >
Crossing threshold value fulfill numeric threshold condition.
- name: Decreasing
description: >
- If threshold value is crossed and previous sensor value was greater
- then threshold value then numeric threshold condition is met.
+ If threshold value is crossed and previous sensor value was
+ greater then threshold value then numeric threshold condition is
+ met.
- name: Increasing
description: >
If threshold value is crossed and previous sensor value was less
diff --git a/yaml/xyz/openbmc_project/Telemetry/TriggerManager.interface.yaml b/yaml/xyz/openbmc_project/Telemetry/TriggerManager.interface.yaml
index e92d269..b6965fa 100644
--- a/yaml/xyz/openbmc_project/Telemetry/TriggerManager.interface.yaml
+++ b/yaml/xyz/openbmc_project/Telemetry/TriggerManager.interface.yaml
@@ -3,28 +3,37 @@
methods:
- name: AddTrigger
- description: Create new object that represent Trigger with
+ description: >
+ Create new object that represents Trigger with
xyz.openbmc_project.Telemetry.Trigger interface stored in path
- /xyz/openbmc_project/Telemetry/Triggers/{Domain}/{Name} where
- Domain and Name are parameters of this method.
+ /xyz/openbmc_project/Telemetry/Triggers/{id} where id is parameter of
+ this method.
parameters:
+ - name: id
+ type: string
+ description: >
+ Defines unique identifier of created Trigger object to be
+ exposed over D-Bus. Acceptable formats are: "{Id}",
+ "{Prefix}/{SubId}", "{Prefix}/". If the last variant is used,
+ service will generate unique SubId value by itself.
- name: name
type: string
description: >
- Defines the name of report to be exposed over D-Bus. Service allows
- to use separator '/' in name to group reports in directory.
+ Defines user friendly name of created Trigger object.
- name: triggerActions
type: array[enum[xyz.openbmc_project.Telemetry.Trigger.TriggerAction]]
description: >
- Defines which actions are taken when threshold conditions are met.
+ Defines which actions are taken when threshold conditions are
+ met.
- name: sensors
- type: array[struct[object_path,string]]
+ type: array[dict[object_path,string]]
description: >
- Array of sensors that is monitored within trigger. Object path
- points to a sensor in DBus envrionment. String is used as user
- metadata.
- - name: reportNames
- type: array[string]
+ Map of sensors that is monitored within trigger. D-Bus sensor
+ path is used as map's key. Its value is a metadata that is used
+ to store user data about sensor. In Redfish, metadata will be
+ set to endpoint corresponding to that sensor.
+ - name: reports
+ type: array[object_path]
description: >
Collection of report names that are updated when threshold
conditions are met. This parameter is ignored if triggerActions
@@ -32,11 +41,11 @@
- name: thresholds
type: variant[array[struct[enum[xyz.openbmc_project.Telemetry.Trigger.Type],uint64,enum[xyz.openbmc_project.Telemetry.Trigger.Direction],double]],array[struct[string,enum[xyz.openbmc_project.Telemetry.Trigger.Severity],uint64,string]]]
description: >
- Contains array of numeric or discrete thresholds that are described
- in xyz.openbmc_project.Telemetry.Trigger interface.
+ Contains array of numeric or discrete thresholds that are
+ described in xyz.openbmc_project.Telemetry.Trigger interface.
returns:
- name: triggerPath
type: object_path
description: >
Path to new trigger ->
- /xyz/openbmc_project/Telemetry/Triggers/{name}.
+ /xyz/openbmc_project/Telemetry/Triggers/{id}.