| README.md (c41693c6a1688e5aa3a9b41b53d402a3b61b7484) | README.md (0a2c1a23327ac720b19eb1b12521d8fde95de2d5) |
|---|---|
| 1# phosphor-logging 2The phosphor logging repository provides mechanisms for event and journal 3logging. 4 5## Table Of Contents 6* [Building](#to-build) 7* [Remote Logging](#remote-logging-via-rsyslog) | 1# phosphor-logging 2The phosphor logging repository provides mechanisms for event and journal 3logging. 4 5## Table Of Contents 6* [Building](#to-build) 7* [Remote Logging](#remote-logging-via-rsyslog) |
| 8* [Event Logs](#event-logs) |
|
| 8* [Application Specific Error YAML](#adding-application-specific-error-yaml) 9* [Event Log Extensions](#event-log-extensions) 10 11## To Build 12``` 13To build this package, do the following steps: 14 15 1. ./bootstrap.sh --- 55 unchanged lines hidden (view full) --- 71#### Disabling remote logging 72Remote logging can be disabled by writing 0 to the port, or an empty string("") 73to the IP. 74 75#### Changing the rsyslog server 76When switching to a new server from an existing one (i.e the address, or port, 77or both change), it is recommended to disable the existing configuration first. 78 | 9* [Application Specific Error YAML](#adding-application-specific-error-yaml) 10* [Event Log Extensions](#event-log-extensions) 11 12## To Build 13``` 14To build this package, do the following steps: 15 16 1. ./bootstrap.sh --- 55 unchanged lines hidden (view full) --- 72#### Disabling remote logging 73Remote logging can be disabled by writing 0 to the port, or an empty string("") 74to the IP. 75 76#### Changing the rsyslog server 77When switching to a new server from an existing one (i.e the address, or port, 78or both change), it is recommended to disable the existing configuration first. 79 |
| 80## Event Logs 81OpenBMC event logs are a collection of D-Bus interfaces owned by 82phosphor-log-manager that reside at `/xyz/openbmc_project/logging/entry/X`, 83where X starts at 1 and is incremented for each new log. |
|
| 79 | 84 |
| 85The interfaces are: 86* [xyz.openbmc_project.Logging.Entry] 87 * The main event log interface. 88* [org.openbmc.Associations] 89 * Used for specifying inventory items as the cause of the event. 90 * For more information on associations, see [here][associations-doc]. 91* [xyz.openbmc_project.Object.Delete] 92 * Provides a Delete method to delete the event. 93* [xyz.openbmc_project.Software.Version] 94 * Stores the code version that the error occurred on. 95 96On platforms that make use of these event logs, the intent is that they are 97the common event log representation that other types of event logs can be 98created from. For example, there is code to convert these into both Redfish 99and IPMI event logs, in addition to the event log extensions mentioned 100[below](#event-log-extensions). 101 102The logging daemon has the ability to add `callout` associations to an event 103log based on text in the AdditionalData property. A callout is a link to the 104inventory item(s) that were the cause of the event log. See [here][callout-doc] 105for details. 106 107### Creating Event Logs In Code 108There are two approaches to creating event logs in OpenBMC code. The first 109makes use of the systemd journal to store metadata needed for the log, and the 110second is a plain D-Bus method call. 111 112#### Journal Based Event Log Creation 113Event logs can be created by using phosphor-logging APIs to commit sdbusplus 114exceptions. These APIs write to the journal, and then call a `Commit` 115D-Bus method on the logging daemon to create the event log using the information 116it put in the journal. 117 118The APIs are found in `<phosphor-logging/elog.hpp>`: 119* `elog()`: Throw an sdbusplus error. 120* `commit()`: Catch an error thrown by elog(), and commit it to create the 121 event log. 122* `report()`: Create an event log from an sdbusplus error without throwing the 123 exception first. 124 125Any errors passed into these APIs must be known to phosphor-logging, usually 126by being defined in `<phosphor-logging/elog-errors.hpp>`. The errors must 127also be known by sdbusplus, and be defined in their corresponding error.hpp. 128See below for details on how get errors into these headers. 129 130Example: 131``` 132#include <phosphor-logging/elog-errors.hpp> 133#include <phosphor-logging/elog.hpp> 134#include <xyz/openbmc_project/Common/error.hpp> 135... 136using InternalFailure = 137 sdbusplus::xyz::openbmc_project::Common::Error::InternalFailure; 138... 139if (somethingBadHappened) 140{ 141 phosphor::logging::report<InternalFailure>(); 142} 143 144``` 145Alternatively, to throw, catch, and then commit the error: 146``` 147try 148{ 149 phosphor::logging::elog<InternalFailure>(); 150} 151catch (InternalFailure& e) 152{ 153 phosphor::logging::commit<InternalFailure>(); 154} 155``` 156 157Metadata can be added to event logs to add debug data captured at the time of 158the event. It shows up in the AdditionalData property in the 159`xyz.openbmc_project.Logging.Entry` interface. Metadata is passed in via the 160`elog()` or `report()` functions, which write it to the journal. The metadata 161must be predefined for the error in the [metadata YAML](#event-log-definition) 162so that the daemon knows to look for it in the journal when it creates the 163event log. 164 165Example: 166``` 167#include <phosphor-logging/elog-errors.hpp> 168#include <phosphor-logging/elog.hpp> 169#include <xyz/openbmc_project/Control/Device/error.hpp> 170... 171using WriteFailure = 172 sdbusplus::xyz::openbmc_project::Control::Device::Error::WriteFailure; 173using metadata = 174 xyz::openbmc_project::Control::Device::WriteFailure; 175... 176if (somethingBadHappened) 177{ 178 phosphor::logging::report<WriteFailure>(metadata::CALLOUT_ERRNO(5), 179 metadata::CALLOUT_DEVICE_PATH("some path")); 180} 181``` 182In the above example, the AdditionalData property would look like: 183``` 184["CALLOUT_ERRNO=5", "CALLOUT_DEVICE_PATH=some path"] 185``` 186Note that the metadata fields must be all uppercase. 187 188##### Event Log Definition 189As mentioned above, both sdbusplus and phosphor-logging must know about the 190event logs in their header files, or the code that uses them will not even 191compile. The standard way to do this to define the event in the appropriate 192`<error-category>.errors.yaml` file, and define any metadata in the 193`<error-category>.metadata.yaml` file in the appropriate `*-dbus-interfaces` 194repository. During the build, phosphor-logging generates the elog-errors.hpp 195file for use by the calling code. 196 197In much the same way, sdbusplus uses the event log definitions to generate an 198error.hpp file that contains the specific exception. The path of the error.hpp 199matches the path of the YAML file. 200 201For example, if in phosphor-dbus-interfaces there is 202`xyz/openbmc_project/Control/Device.errors.yaml`, the errors that come from 203that file will be in the include: 204`xyz/openbmc_project/Control/Device/error.hpp`. 205 206In rare cases, one may want one to define their errors in the same repository 207that uses them. To do that, one must: 208 2091. Add the error and metadata YAML files to the repository. 2102. Run the sdbus++ script within the makefile to create the error.hpp and .cpp 211 files from the local YAML, and include the error.cpp file in the application 212 that uses it. See [openpower-occ-control] for an example. 2133. Tell phosphor-logging about the error. This is done by either: 214 * Following the [directions](#adding-application-specific-error-yaml) 215 defined in this README, or 216 * Running the script yourself: 217 1. Run phosphor-logging\'s `elog-gen.py` script on the local yaml to 218 generate an elog-errors.hpp file that just contains the local errors, 219 and check that into the repository and include it where the errors are 220 needed. 221 2. Create a recipe that copies the local YAML files to a place that 222 phosphor-logging can find it during the build. See [here][led-link] 223 for an example. 224 225#### D-Bus Event Log Creation 226**TODO** 227 228[xyz.openbmc_project.Logging.Entry]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Logging/Entry.interface.yaml 229[org.openbmc.Associations]: https://github.com/openbmc/phosphor-logging/blob/master/org/openbmc/Associations.interface.yaml 230[associations-doc]: https://github.com/openbmc/docs/blob/master/object-mapper.md#associations 231[callout-doc]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Common/Callout/README.md 232[xyz.openbmc_project.Object.Delete]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Object/Delete.interface.yaml 233[xyz.openbmc_project.Software.Version]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Software/Version.errors.yaml 234[elog-errors.hpp]: https://github.com/openbmc/phosphor-logging/blob/master/phosphor-logging/elog.hpp 235[openpower-occ-control]: https://github.com/openbmc/openpower-occ-control 236[led-link]: https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/leds 237 |
|
| 80## Adding application specific error YAML 81* This document captures steps for adding application specific error YAML files 82 and generating local elog-errors.hpp header file for application use. 83* Should cater for continuous integration (CI) build, bitbake image build, and 84 local repository build. 85 86#### Continuous Integration (CI) build 87 * Make is called on the repository that is modified. --- 270 unchanged lines hidden --- | 238## Adding application specific error YAML 239* This document captures steps for adding application specific error YAML files 240 and generating local elog-errors.hpp header file for application use. 241* Should cater for continuous integration (CI) build, bitbake image build, and 242 local repository build. 243 244#### Continuous Integration (CI) build 245 * Make is called on the repository that is modified. --- 270 unchanged lines hidden --- |