phosphor-logging/docs/structured-logging.md

1 # Structured Logging
3 There are currently two APIs for structured logging:
4 [log](../lib/include/phosphor-logging/log.hpp) and
5 [lg2](../lib/include/phosphor-logging/lg2.hpp). If your code is C++20 (or later)
8 ## Why structured logging?
10 Structured logging is a method of logging where every variable piece of data is
12 logging where logged events are free-form strings.
14 The principal logging daemon in OpenBMC (systemd-journald) natively supports
15 structured logging. As a result, there are some designs in place where specific
21 form of IPC, the value of structured logging persists. It is very common as part
24 when/where/why a situation degraded. With unstructured logging, the
26 structured logging the format is somewhat static and easily parsed.
28 A specific example of where structured logging is beneficial is a service which
37 For deeper understanding of the OpenBMC logging subsystem, it may be useful to
44 The pre-C++20 logging APIs presented by phosphor-logging are
45 `phosphor::logging::log`. The basic format of a log call is:
67 The post-C++20 logging APIs presented by phosphor-logging are `lg2::log`. The
177 - `%f` : the logging function's name
178 - `%F` : the logging function's file
180 - `%L` : the logging function's line number
187 There were a number of issues raised by `logging::log` which are not easily
195 3. `logging::log` generates incorrect code location information (see
202 5. When running on a TTY, `logging::log` sent data to journal and the TTY was
204    data to `stdout` and some to `logging::log` APIs. `lg2` automatically detects
205    if it is running on a TTY and duplicates logging data to the console and the
214 It is possible that this could be solved in the `logging::log` APIs by utilizing
228 `{fmt}` is a great API for creating unstructured logging strings, but we are
229 trying to create structured logging. `{fmt}` doesn't address that problem
236 typical use-case for our logging. Instead we prioritized the following:
241 4. Very tight code generation at logging call sites and reasonably performant
260 providing the source-code information, compared to the older `logging` APIs and
272 Logging is done often. Shifting a few values onto the stack for a printf-type
297 adoption of the `logging` API by some members of the development community.
298 Unless we dispense with structured logging entirely, this duplication seems like
318 named argument with a `fmt::arg` call, which is similar to `logging`'s `entry`.