xref: /openbmc/phosphor-dbus-monitor/src/example/example.yaml (revision f7a6a462e357726fa20aa487d838a4890100d46f)
1# Example PDM configuration file.
2
3- name: example path group
4  description: >
5    'A path group is a named collection of D-Bus object
6    paths and associated metadata.  These collections
7    serve only to be referenced by other configuration
8    directives.
9
10    The metadata element has different uses depending
11    on the referencing directive.
12
13    Within a single configuration file path group names
14    must be unique.  The same name can appear in multiple
15    configuration files; however, the referencing directive
16    will only search for the group in the same configuration
17    file.'
18  class: group
19  group: path
20  members:
21    - meta: PATH
22      path: /xyz/openbmc_project/testing/inst1
23    - meta: PATH
24      path: /xyz/openbmc_project/testing/inst2
25    - meta: PATH
26      path: /xyz/openbmc_project/testing/inst3
27    - meta: PATH
28      path: /xyz/openbmc_project/testing/inst4
29
30- name: example property group
31  description: >
32    'Like path groups, a property group is a named collection
33    of D-Bus property names and associated metadata.
34
35    Properties in a group must all have the same D-Bus type signature
36    and must be explicitly declared.'
37  class: group
38  group: property
39  type: uint32
40  members:
41    - interface: xyz.openbmc_project.Sensor.Value
42      meta: PROPERTY
43      property: ValueA
44    - interface: xyz.openbmc_project.Sensor.Value
45      meta: PROPERTY
46      property: ValueB
47
48- name: example property watch
49  description: >
50    'A property watch instructs PDM to maintain a cache of the state
51    of the specified properties on the specified D-Bus objects.
52
53    An optional callback can be triggered when property values change.'
54  class: watch
55  watch: property
56  paths: example path group
57  properties: example property group
58  callback: example count condition
59
60- name: example journal callback
61  description: >
62    'Callbacks are actions PDM should take when instructed to do so.
63
64    Some callback types refer to a group of paths and group of properties
65    in a similar fashion as the property watch directive.
66
67    The journal callback logs the specified message to the systemd journal
68    with the specified severity.
69
70    Additionally, the journal callback will add to the journal key value
71    pair metadata for each property in the specified property group with
72    the key being the property element metadata and the value being the
73    property value.'
74  class: callback
75  callback: journal
76  paths: example path group
77  properties: example property group
78  severity: INFO
79  message: Hello world from PDM!
80
81- name: example elog callback
82  description: >
83    'Callbacks are actions PDM should take when instructed to do so.
84
85    Some callback types refer to a group of paths and group of properties
86    in a similar fashion as the property watch directive.
87
88    The elog callback logs the elog and elog metadata.'
89  class: callback
90  callback: elog
91  paths: example path group
92  properties: example property group
93  error: xyz::openbmc_project::Common::Error::InvalidArgument
94  metadata:
95    - name: xyz::openbmc_project::Common::InvalidArgument::ARGUMENT_NAME
96      value: testing...
97      type: string
98    - name: xyz::openbmc_project::Common::InvalidArgument::ARGUMENT_VALUE
99      value: testing...
100      type: string
101
102- name: example method callback
103  description: >
104    'The method callback invokes the specified D-Bus method.'
105  class: callback
106  callback: method
107  service: org.freedesktop.systemd1
108  path: /org/freedesktop/systemd1
109  interface: org.freedesktop.systemd1.Manager
110  method: StartUnit
111  args:
112    - value: foo.unit
113      type: string
114    - value: replace
115      type: string
116
117- name: example resolve callouts callback
118  description: >
119    'The resolve callout callback resolves all error log entries that
120    are associated with the inventory path specified by setting the
121    Resolved property in the entries to true.
122
123    A use case could be to watch the Present property on the inventory
124    item and resolve all errors for it when a new one is plugged in and
125    the property changes to true.'
126
127  class: callback
128  callback: resolve callout
129  paths: example path group
130  properties: example property group
131  callout: /xyz/openbmc_project/inventory/system/chassis/motherboard/fan0
132
133- name: example callback group
134  description: >
135    'Callbacks groups are simply named collections of other callbacks.
136    Configuration file directives can only refer to a single callback.
137    Through use of a group, these configuration file directives can
138    refer to more than one callback.
139
140    For example for a given event, one may wish to trace multiple
141    messages to the systemd journal.  The journal callback does not
142    support tracing multiple messages.  To do that, define a callback
143    group composed of multiple journal callbacks.'
144
145  class: callback
146  callback: group
147  members:
148    - example journal callback
149    - example deferred condition
150    - example elog callback
151
152- name: example count condition
153  description: >
154    'Conditions or conditional callbacks apply a test prior to invoking
155    the callback function.
156
157    All conditional callbacks must specify the callback to issue if
158    the condition evaluates.
159
160    The count condition applies the op comparison operator to the value of each
161    property in the specified groups.  It then counts the number of properties
162    that pass the comparison, and applies another comparison on the result
163    against the specified bound.
164
165    For example, a callback that requires at least three temperature sensors
166    in the group to be higher than 115 degrees might use a count condition
167    with an op of >, a count op of >=, a bound of 115, and a countbound of 3.'
168
169  class: condition
170  condition: count
171  paths: example path group
172  properties: example property group
173  callback: example callback group
174  countop: '>='
175  countbound: 3
176  op: '>='
177  bound: 115
178
179- name: example deferred condition
180  description: >
181    'Deferred conditions operate in the same fashion as conditional callbacks
182    with the added behavior that when the condition is tested and is met,
183    invocation of the callback is deferred by the interval specified.
184
185    When the configured time has elapsed, if the condition has not been reevaluated
186    the callback is invoked.
187
188    Any condition type can be deferred in this way by setting the defer attribute.'
189
190  class: condition
191  condition: count
192  paths: example path group
193  properties: example property group
194  defer: 1000us
195  callback: example callback group
196  countop: '>='
197  countbound: 3
198  op: '>='
199  bound: 115
200