1# OpenBMC logging
2
3- Provides a mechanism for logging events and errors to the journal.
4- Creates error entry D-Bus objects when an error is reported/committed.
5- Persists error entries across power off.
6
7## Error definitions
8
9### Generic error definitions
10
11- Generic errors used by applications are defined at
12  [phosphor-dbus-interfaces][phosphor-dbus-interfaces].
13- Generic errors can be used by all the applications by including the generated
14  elog-errors.hpp header file.
15
16[phosphor-dbus-interfaces]: https://github.com/openbmc/phosphor-dbus-interfaces
17
18### Application error definitions
19
20- There are errors that are not generic and are very specific to the
21  application. Such errors are defined in the application that uses the error.
22- Refer to [openpower-debug-collector][openpower-debug-collector].
23
24[openpower-debug-collector]:
25  https://github.com/openbmc/openpower-debug-collector
26
27### Error YAML files
28
29- Every error defined will have an error YAML file and a corresponding error
30  metadata YAML file.
31- The error YAML file contains the error name and a one-line description of the
32  error. An example of an error YAML file can be found [here][error-example].
33- The error metadata YAML file captures required data. The format of the data is
34  defined in the error metadata file. An example of an error metadata YAML file
35  can be found [here][metadata-example].
36
37[error-example]:
38  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Common/File.errors.yaml
39[metadata-example]:
40  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Common/File.metadata.yaml
41
42## Logging to journal
43
44- Applications can log debug/error information to the journal using the **log**
45  API
46  - Refer to [log.hpp][log-header].
47- Applications can commit errors to the journal using the **report** or
48  **commit** API
49  - Refer to [elog.hpp][elog-header].
50  - Logging entry D-Bus objects are created for the committed errors.
51
52[log-header]:
53  https://github.com/openbmc/phosphor-logging/blob/master/lib/include/phosphor-logging/log.hpp
54[elog-header]:
55  https://github.com/openbmc/phosphor-logging/blob/master/lib/include/phosphor-logging/elog.hpp
56
57## Delete All interface
58
59- Use the [DeleteAll.interface.yaml][deleteall] for deleting all the logging
60  entries.
61
62[deleteall]:
63  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Collection/DeleteAll.interface.yaml
64
65## REST commands
66
67### Logging in
68
69- Before you can do anything, you need to first login.
70
71```sh
72export bmc=xx.xx.xx.xx
73curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
74    -d '{"data": [ "root", "<root-password>" ] }' \
75    https://{$bmc}/login
76```
77
78### List logging child objects recursively
79
80```sh
81curl -c cjar -b cjar -k https://${bmc}/xyz/openbmc_project/logging/list
82```
83
84### List logging attributes of child objects recursively
85
86```sh
87curl -c cjar -b cjar -s -k -H "Content-Type: application/json" -X GET \
88    -d '{"data" : []}' \
89    https://${bmc}/xyz/openbmc_project/logging/enumerate
90```
91
92### Delete logging entries
93
94```sh
95curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
96    -d '{"data": []}' \
97    https://${bmc}/xyz/openbmc_project/logging/entry/<entry-num>/action/Delete
98```
99
100### Delete all logging entries
101
102```sh
103curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
104    -d "{\"data\": [] }" \
105    https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
106```
107