xref: /openbmc/phosphor-dbus-interfaces/yaml/xyz/openbmc_project/Telemetry/Report.interface.yaml (revision 9d46e5bb0fcad6c4a775dcef781c0ce4b9de1ff5)

description: >
    Implement this interface to provide report inspection features. An
    implementation service should additionally implement
    xyz.openbmc_project.Object.Delete for deletion of individual report objects.

methods:
    - name: Update
      description: >
          The Update method is defined for the on demand metric report update.
          It triggers update of the Readings property. If ReportingType is not
          set to OnRequest then method does nothing.
    - name: SetReadingProperties
      description: >
          Performs safe modification of ReportingType and Interval properties
          from this interface with additional checking if provided pair of
          arguments is allowed.
      parameters:
          - name: ReportingType
            type: enum[self.ReportingType]
            description: >
                Indicates how readings should be updated. Possible values are
                listed in details for corresponding enum.
          - name: Interval
            type: uint64
            description: >
                Period of time in milliseconds when readings are updated.

properties:
    - name: Persistency
      type: boolean
      description: >
          Defines if the report configuration is stored in non volatile memory.
          Configuration contains all Report properties excluding Readings.
    - name: ReadingParameters
      type: array[struct[array[struct[object_path,string]],enum[self.OperationType],string,enum[self.CollectionTimescope],uint64]]
      description: >
          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.
      flags:
          - readonly
    - name: ReportingType
      type: enum[self.ReportingType]
      description: Defines how readings are updated.
      flags:
          - readonly
    - name: ReportUpdates
      type: enum[self.ReportUpdates]
      description: Defines how Readings array is filled.
    - name: AppendLimit
      type: size
      description: Defines the maximum number of entries in 'Readings' property.
      flags:
          - readonly
    - name: Interval
      type: uint64
      description: >
          Defines period of time in milliseconds when readings are updated.
      flags:
          - readonly
    - name: Enabled
      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.
    - 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: 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.
      values:
          - name: OnChange
            description: >
                On sensor reading change.
          - name: OnRequest
            description: >
                On Update method call.
          - name: Periodic
            description: >
                After period of time defined by Interval property.
    - name: ReportUpdates
      description: >
          The type that defines how Readings are updated.
      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.
          - name: AppendWrapsWhenFull
            description: >
                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: CollectionTimescope
      description: >
          The time scope of the related metric values.
      values:
          - name: Point
            description: >
                The corresponding metric apply to a point in time. The reading
                timestamp in Readings property specifies point in time.
          - 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.
          - 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
                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.