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]: https://github.com/openbmc/openpower-debug-collector
25
26### Error YAML files
27
28- Every error defined will have an error YAML file and a corresponding error
29  metadata YAML file.
30- The error YAML file contains the error name and a one-line description of the
31  error.
32  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
34  is defined in the error metadata file. An example of an error metadata YAML
35  file can be found [here][metadata-example].
36
37[error-example]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Common/File.errors.yaml
38[metadata-example]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Common/File.metadata.yaml
39
40## Logging to journal
41
42- Applications can log debug/error information to the journal using
43  the **log** API
44  - Refer to [log.hpp][log-header].
45- Applications can commit errors to the journal using the **report** or
46  **commit** API
47  - Refer to [elog.hpp][elog-header].
48  - Logging entry D-Bus objects are created for the committed errors.
49
50[log-header]: https://github.com/openbmc/phosphor-logging/blob/master/lib/include/phosphor-logging/log.hpp
51[elog-header]: https://github.com/openbmc/phosphor-logging/blob/master/lib/include/phosphor-logging/elog.hpp
52
53## Delete All interface
54
55- Use the [DeleteAll.interface.yaml][deleteall] for deleting all the logging
56  entries.
57
58[deleteall]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Collection/DeleteAll.interface.yaml
59
60## REST commands
61
62### Logging in
63
64- Before you can do anything, you need to first login.
65
66```sh
67export bmc=xx.xx.xx.xx
68curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
69    -d '{"data": [ "root", "<root-password>" ] }' \
70    https://{$bmc}/login
71```
72
73### List logging child objects recursively
74
75```sh
76curl -c cjar -b cjar -k https://${bmc}/xyz/openbmc_project/logging/list
77```
78
79### List logging attributes of child objects recursively
80
81```sh
82curl -c cjar -b cjar -s -k -H "Content-Type: application/json" -X GET \
83    -d '{"data" : []}' \
84    https://${bmc}/xyz/openbmc_project/logging/enumerate
85```
86
87### Delete logging entries
88
89```sh
90curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
91    -d '{"data": []}' \
92    https://${bmc}/xyz/openbmc_project/logging/entry/<entry-num>/action/Delete
93```
94
95### Delete all logging entries
96
97```sh
98curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
99    -d "{\"data\": [] }" \
100    https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
101```
102