NVIDIA/phosphor-logging

NVIDIA/phosphor-logging

Description: Libraries for common event and logging creation.

Language: C++

License: Apache-2.0

Stars: 2

Forks: 1

Open issues: 0

Created: 2024-05-06T16:47:57Z

Pushed: 2026-06-10T18:08:32Z

Default branch: develop

Fork: yes

Parent repository: openbmc/phosphor-logging

Archived: no

README:

phosphor-logging

The phosphor logging repository provides mechanisms for event and journal logging.

Table Of Contents

• [Building](#to-build)
• [Structured Logging](#structured-logging)
• [Event Logs](#event-logs)
• [Event Log Extensions](#event-log-extensions)
• [Remote Logging](#remote-logging-via-rsyslog)
• [Boot Fail on Hardware Errors](#boot-fail-on-hardware-errors)
• [Encoding BMC position in entry ID](#encoding-the-bmc-position-in-the-entry-id)

To Build

To build this package, do the following steps:

1. meson builddir 2. ninja -c builddir

Structured Logging

phosphor-logging provides APIs to add program logging information to the systemd-journal and it is preferred that this logging data is formatted in a structured manner (using the facilities provided by the APIs).

See [Structured Logging](./docs/structured-logging.md) for more details on this API.

Event Logs

OpenBMC event logs are a collection of D-Bus interfaces owned by phosphor-log-manager that reside at /xyz/openbmc_project/logging/entry/X, where X starts at 1 and is incremented for each new log.

The interfaces are:

• [xyz.openbmc_project.Logging.Entry]
• The main event log interface.
• [xyz.openbmc_project.Association.Definitions]
• Used for specifying inventory items as the cause of the event.
• For more information on associations, see the [associations

doc][associations-doc].

• [xyz.openbmc_project.Object.Delete]
• Provides a Delete method to delete the event.
• [xyz.openbmc_project.Software.Version]
• Stores the code version that the error occurred on.

On platforms that make use of these event logs, the intent is that they are the common event log representation that other types of event logs can be created from. For example, there is code to convert these into both Redfish and IPMI event logs, in addition to the event log extensions mentioned [below](#event-log-extensions).

The logging daemon has the ability to add callout associations to an event log based on text in the AdditionalData property. A callout is a link to the inventory item(s) that were the cause of the event log. See [callout doc][callout-doc] for details.

Creating Event Logs In Code

The preferred method for creating event logs is specified in the project-level [event log design][event-log-design]. Events are defined using YAML in the phosphor-dbus-interfaces repository, such as the [Logging.Cleared][logging-cleared] event, which will generate a C++ class for the event. Then a call to lg2::commit is made on a constructed event to add it to the event log.

lg2::commit(sdbusplus::event::xyz::openbmc_project::Logging::Cleared(
"NUMBER_OF_LOGS", count));

The above function will return the object path of the created log entry. This log-entry can be resolved with the helper lg2::resolve function.

lg2::resolve(logPath);

Services may override the default assigned severity of the event by providing the optional parameter:

#include
lg2::commit(sdbusplus::event::xyz::openbmc_project::Logging::Cleared(
"NUMBER_OF_LOGS", count), LOG_CRIT);

Event Log Filtering

Vendors customizing phosphor-logging for their platforms may decide that they would like to prevent certain events from being added to the event log. This is especially true for informational / tracing events. The lg2::commit supports a compile-time event filtering mechanism that can accomplish this.

The meson option event-filter can be used to specify a file containing filtering policy. When left unspecified, the [default policy][default-policy-json] of "allow all" is enabled. For both events and errors, a default policy of "allowed" or "blocked" can be specified and an additional set of events can be given for which the non-defaulted action should be taken. A JSON-Schema is available for the [policy JSON][filter-policy-schema].

[default-policy-json]: https://github.com/openbmc/phosphor-logging/blob/master/tools/phosphor-logging/default-eventfilter.json [filter-policy-schema]: https://github.com/openbmc/phosphor-logging/blob/master/tools/phosphor-logging/schemas/eventfilter.schema.yaml

Deprecated Methods for Creating Event Logs

There are two other, but now deprecated, methods to creating event logs in OpenBMC code. The first makes use of the systemd journal to store metadata needed for the log, and the second is a plain D-Bus method call.

[event-log-design]: https://github.com/openbmc/docs/blob/master/designs/event-logging.md#phosphor-logging [logging-cleared]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/6a8507d06e172d8d29c0459f0a0d078553d2ecc7/yaml/xyz/openbmc_project/Logging.events.yaml#L4

Journal Based Event Log Creation [deprecated]

Event logs can be created by using phosphor-logging APIs to commit sdbusplus exceptions. These APIs write to the journal, and then call a Commit D-Bus method on the logging daemon to create the event log using the information it put in the journal.

The APIs are found in ``:

• elog(): Throw an sdbusplus error.
• commit(): Catch an error thrown by elog(), and commit it to create the event

log.

• report(): Create an event log from an sdbusplus error without throwing the

exception first.

Any errors passed into these APIs must be known to phosphor-logging, usually by being defined in ``. The errors must also be known by sdbusplus, and be defined in their corresponding error.hpp. See below for details on how get errors into these headers.

Example:

#include
#include
#include
...
using InternalFailure =
sdbusplus::xyz::openbmc_project::Common::Error::InternalFailure;
...
if (somethingBadHappened)
{
phosphor::logging::report();
}

Alternatively, to throw, catch, and then commit the error:

try
{
phosphor::logging::elog();
}
catch (InternalFailure& e)
{
phosphor::logging::commit();
}

Metadata can be added to event logs to add debug data captured at the time of the event. It shows up in the AdditionalData property in the xyz.openbmc_project.Logging.Entry interface. Metadata is passed in via the elog() or report() functions, which write it to the journal. The metadata must be predefined for the error...