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