openbmc/phosphor-logging/README.md

1 # phosphor-logging
8 - [Building](#to-build)
9 - [Structured Logging](#structured-logging)
10 - [Event Logs](#event-logs)
11 - [Event Log Extensions](#event-log-extensions)
12 - [Remote Logging](#remote-logging-via-rsyslog)
13 - [Boot Fail on Hardware Errors](#boot-fail-on-hardware-errors)
20 2. ninja -c builddir
24 phosphor-logging provides APIs to add program logging information to the
25 systemd-journal and it is preferred that this logging data is formatted in a
28 See [Structured Logging](./docs/structured-logging.md) for more details on this
33 OpenBMC event logs are a collection of D-Bus interfaces owned by
34 phosphor-log-manager that reside at `/xyz/openbmc_project/logging/entry/X`,
39 - [xyz.openbmc_project.Logging.Entry]
40   - The main event log interface.
41 - [xyz.openbmc_project.Association.Definitions]
42   - Used for specifying inventory items as the cause of the event.
43   - For more information on associations, see the [associations
44     doc][associations-doc].
45 - [xyz.openbmc_project.Object.Delete]
46   - Provides a Delete method to delete the event.
47 - [xyz.openbmc_project.Software.Version]
48   - Stores the code version that the error occurred on.
54 [below](#event-log-extensions).
59 doc][callout-doc] for details.
63 The preferred method for creating event logs is specified in the project-level
64 [event log design][event-log-design]. Events are defined using YAML in the
65 phosphor-dbus-interfaces repository, such as the
66 [Logging.Cleared][logging-cleared] event, which will generate a C++ class for
76 log-entry can be resolved with the helper `lg2::resolve` fuction.
84 Vendors customizing phosphor-logging for their platforms may decide that they
87 compile-time event filtering mechanism that can accomplish this.
89 The meson option `event-filter` can be used to specify a file containing
91 policy][default-policy-json] of "allow all" is enabled. For both events and
93 additional set of events can be given for which the non-defaulted action should
94 be taken. A JSON-Schema is available for the [policy
95 JSON][filter-policy-schema].
97 [default-policy-json]:
98 …https://github.com/openbmc/phosphor-logging/blob/master/tools/phosphor-logging/default-eventfilter…
99 [filter-policy-schema]:
100 …https://github.com/openbmc/phosphor-logging/blob/master/tools/phosphor-logging/schemas/eventfilter…
102 ### Deprecated Methods for Creating Event Logs
104 There are two other, but now deprecated, methods to creating event logs in
106 needed for the log, and the second is a plain D-Bus method call.
108 [event-log-design]:
109   https://github.com/openbmc/docs/blob/master/designs/event-logging.md#phosphor-logging
110 [logging-cleared]:
111 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/6a8507d06e172d8d29c0459f0a0d078553d2ecc7/…
113 #### Journal Based Event Log Creation [deprecated]
115 Event logs can be created by using phosphor-logging APIs to commit sdbusplus
116 exceptions. These APIs write to the journal, and then call a `Commit` D-Bus
120 The APIs are found in `<phosphor-logging/elog.hpp>`:
122 - `elog()`: Throw an sdbusplus error.
123 - `commit()`: Catch an error thrown by elog(), and commit it to create the event
125 - `report()`: Create an event log from an sdbusplus error without throwing the
128 Any errors passed into these APIs must be known to phosphor-logging, usually by
129 being defined in `<phosphor-logging/elog-errors.hpp>`. The errors must also be
136 #include <phosphor-logging/elog-errors.hpp>
137 #include <phosphor-logging/elog.hpp>
173 #include <phosphor-logging/elog-errors.hpp>
174 #include <phosphor-logging/elog.hpp>
197 ##### Event Log Definition [deprecated]  argument
199 As mentioned above, both sdbusplus and phosphor-logging must know about the
202 `<error-category>.errors.yaml` file, and define any metadata in the
203 `<error-category>.metadata.yaml` file in the appropriate `*-dbus-interfaces`
204 repository. During the build, phosphor-logging generates the elog-errors.hpp
211 For example, if in phosphor-dbus-interfaces there is
221    that uses it. See [openpower-occ-control] for an example.
222 3. Tell phosphor-logging about the error:
223    1. Run phosphor-logging's `elog-gen.py` script on the local yaml to generate
224       an elog-errors.hpp file that just contains the local errors, and check
227       phosphor-logging can find it during the build. See sample [LED
228       YAML][led-link] for an example.
230 #### D-Bus Event Log Creation [deprecated]
232 There is also a [D-Bus method][log-create-link] to create event logs:
234 - Service: xyz.openbmc_project.Logging
235 - Object Path: /xyz/openbmc_project/logging
236 - Interface: xyz.openbmc_project.Logging.Create
237 - Method: Create
238   - Method Arguments:
239     - Message: The `Message` string property for the
241     - Severity: The `severity` property for the
244     - AdditionalData: The `AdditionalData` property for the
254 thrown across D-Bus, this API does not require that the error be defined in the
255 error YAML in the D-Bus interfaces repository so that sdbusplus knows about it.
278    metadata YAML files in the appropriate D-Bus interfaces repository so that
283 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Logging/E…
285 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Associati…
286 [associations-doc]:
287   https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
288 [callout-doc]:
289 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Common/Ca…
291 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/De…
293 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/…
294 [openpower-occ-control]: https://github.com/openbmc/openpower-occ-control
295 [led-link]:
296   https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/leds
297 [log-create-link]:
298 …https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Logging/C…
303 logs besides phosphor-logging's event logs to still reside in the
304 phosphor-log-manager application.
307 enabled with a `--enable-<extension>` configure flag. The extension code won't
313 - On startup
314   - Function type void(internal::Manager&)
315 - After an event log is created
316   - Function type void(args)
317   - The args are:
318     - const std::string& - The Message property
319     - uin32_t - The event log ID
320     - uint64_t - The event log timestamp
321     - Level - The event level
322     - const AdditionalDataArg& - the additional data
323     - const AssociationEndpointsArg& - Association endpoints (callouts)
324 - Before an event log is deleted, to check if it is allowed.
325   - Function type void(std::uint32_t, bool&) that takes the event ID
326 - After an event log is deleted
327   - Function type void(std::uint32_t) that takes the event ID
333 In addition, an extension has the option of disabling phosphor-logging's default
339 The reason for adding support for extensions inside the phosphor-log-manager
340 daemon as opposed to just creating new daemons that listen for D-Bus signals is
342 D-Bus, such as:
344 - Allowing for custom old log retention algorithms.
345 - Prohibiting manual deleting of certain logs based on an extension's
353    AC_ARG_ENABLE([foo-extension],
354                  AS_HELP_STRING([--enable-foo-extension],
361 3. Create a makefile include to add the new code to phosphor-log-manager:
410 - OpenPower PELs
411   - Enabled with --enable-openpower-pel-extension
412   - Detailed information can be found in
413     [extensions/openpower-pels](extensions/openpower-pels/README.md).
423 <https://www.rsyslog.com/storing-and-forwarding-remote-messages/>
425 <https://www.thegeekdiary.com/understanding-rsyslog-filter-options/>
434 <https://github.com/openbmc/docs/blob/master/rest-api.md>).
439 curl -b cjar -k -H "Content-Type: application/json" -X PUT \
440     -d '{"data": <IP address>}' \
447 curl -b cjar -k -H "Content-Type: application/json" -X PUT \
448     -d '{"data": <port number>}' \
455 curl -b cjar -k \
466 curl -b cjar -k -H "Content-Type: application/json" -X PUT \
467     -d '{"data": "myHostName"}' \
483 phosphor-logging supports a setting, which when set, will result in the software
484 looking at new phosphor-logging entries being created, and if a CALLOUT\* is
490 [docs](https://github.com/openbmc/docs/blob/master/designs/fail-boot-on-hw-error.md).
495 busctl set-property xyz.openbmc_project.Settings /xyz/openbmc_project/logging/settings xyz.openbmc_…
498 To check if an entry is blocking the boot: