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
TRACE. This document summarizes the normative guidelines in RFC-0003: Logging.
||An unrecoverable error event. Should cause termination.|
||An unexpected event from which the program can recover, indicates a bug or undesired program behavior.|
||An unexpected event has occurred within normal operation of the system.|
||An informative event, typically expected. Usually the lowest level in bug reports.|
||An informative event for development.|
||An informative event for development, emitted at fine granularity or high frequency.|
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,
recoverable events which represent incorrect program behavior (i.e. "bugs"), and
recoverable events which are not themselves bugs but which may provide important context about other
You should log events that are only relevant to a contributor working locally on a project as
TRACE. If the events are expected, you should generally log them as
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
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
TRACEseverity because those are excluded from bug reports by default.
INFOand 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
TRACEand 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.