docs/development/diagnostics/logs/severity.md

# Choosing severity for log records

The purpose of this document is to help you choose the correct severity for your log records.
Fuchsia supports log records with severity equal to one of `FATAL`, `ERROR`, `WARNING`, `INFO`,
`DEBUG`, or `TRACE`. This document summarizes the normative guidelines in [RFC-0003: Logging].

<table>
  <tr>
    <td>Severity</td>
    <td>Summary</td>
  </tr>
  <tr>
    <td><code>FATAL</code></td>
    <td>An unrecoverable error event. Should cause termination.</td>
  </tr>
  <tr>
   <td><code>ERROR</code></td>
   <td>
   An unexpected event from which the program can recover, indicates a bug or undesired program
   behavior.
   </td>
  </tr>
  <tr>
   <td><code>WARNING</code></td>
   <td>An unexpected event has occurred within normal operation of the system.</td>
  </tr>
  <tr>
   <td><code>INFO</code></td>
   <td>An informative event, typically expected. Usually the lowest level in bug reports.</td>
  </tr>
  <tr>
   <td><code>DEBUG</code></td>
   <td>An informative event for development.</td>
  </tr>
  <tr>
   <td><code>TRACE</code></td>
   <td>An informative event for development, emitted at fine granularity or high frequency.</td>
  </tr>
</table>

## Not sure which to use?

Log records describe events in the system. Choosing the severity for a log record is one way of
describing the event itself.

Unexpected events should generally be logged at `FATAL` for unrecoverable events, `ERROR` for
recoverable events which represent incorrect program behavior (i.e. "bugs"), and `WARNING` for
recoverable events which are not themselves bugs but which may provide important context about other
failures.

You should log events that are only relevant to a contributor working locally on a project as
`DEBUG` or `TRACE`. If the events are expected, you should generally log them as `INFO`.

If you are still unsure how to label the event severity, consider the following questions:

* What change(s) did the event cause? What was different before and after the event?

  This is usually a matter of writing or reading the message for the event in question. If no change
  occurred in the system, it may be better to skip the event entirely. For important heartbeat events,
  consider `TRACE` severity.

* Who wants to know about this event?

  Events at different severities are available by default in different contexts, which in practice
  defines their audience. Many events are relevant to an engineer working on a project but would
  create too much noise for other teams — it's usually best to emit these events at `DEBUG` or
  `TRACE` severity because those are excluded from bug reports by default.

  Because `INFO` and above are more visible, events which do not provide critical context for an
  implementor when debugging should be limited to information which is useful to clients or others
  outside the implementing team.

* Is this event recurring or ongoing?

  Log events which describe a frequent background activity or an ongoing failure state should be
  limited to `DEBUG` or `TRACE` and also reported by Inspect and Cobalt to avoid production log spam.
  While the entry into a failure state may be useful to log, it is not generally useful to log events
  that say things like "still in the failure state".

  It is difficult to avoid repeating log statements this way when a failure state is "flapping" or
  resolving and unresolving itself regularly. Rate limiting by repetition count or time interval can
  be an appropriate response, but Fuchsia's logging libraries do not currently offer out-of-the-box
  tools for this. It may be explored in the future if a clearer set of patterns and best practices
  emerge.

<!--xrefs-->
[RFC-0003: Logging]: /docs/contribute/governance/rfcs/0003_logging.md