Logs
Logs are OpenTelemetry's approach to incorporating logging information into the observability, enriching it with additional telemetry data and linking it to relevant OpenTelemetry traces.
For that purpose, log entries follow an abstract and generalized path and support both unstructured text and structured information.
How to use OpenTelemetry logs
Unlike traces and metrics, logs are not supposed to be used directly by developers or applications.
Instead of managing logs manually, use the trace APIs to add events in the context of trace-related logs (trace events) and one of the log bridges for your logging library when handling traditional logging information.
In the absence of an available bridge, it is also possible to use the Collector to import from arbitrary sources (for example, log files). For details, see the OpenTelemetry documentation.
Log fields
Each log entry supports the following fields. Each is optional but should be provided if available.
Timestamp—the time when it was logged
ObservedTimestamp—the time when it was logged/observed
SeverityText—the name of the log level under which it was logged
SeverityNumber—the numerical representation of the log level
- Body—the payload (for example, a string, number, Boolean, array, or map)
Resource—a list of sources from which the log originated
TraceId—the trace ID, if logged in the context of tracing
SpanId—the span ID, if logged in the context of tracing
TraceFlags—the trace flags, if logged in the context of tracing
InstrumentationScope—the scope under which it was logged (name and version)
Attributes—a list of attributes associated with this log
Additional information on errors and exceptions can be added as attributes, whose names must follow the semantic conventions for exception-related attributes (exception.message, exception.type, and exception.stacktrace).
Log levels
OpenTelemetry defines 24 log levels in six categories, with four levels per category.
| Name | Levels | Description |
|---|---|---|
| TRACE | 1-4 | A fine-grained debugging event. Typically disabled in default configurations. |
| DEBUG | 5-8 | A debugging event. |
| INFO | 9-12 | An informational event. Indicates that an event happened. |
| WARN | 13-16 | A warning event. Not an error but is likely more important than an informational event. |
| ERROR | 17-20 | An error event. Something went wrong. |
| FATAL | 21-24 | A fatal error such as an application or system crash. |
Categories adhere to classic log-level naming conventions. The lower the level, the more granular and less critical the information of the entry is supposed to be.
Log types
There are two main log entry types: embedded and standalone.
Embedded
Embedded logs are typically created in the context of a trace's span, to which they are linked via their context fields (TraceId and SpanId).
From the perspective of a trace, embedded logs are usually called events, but are still technically log entries.
Standalone
Standalone logs are unrelated to tracing and can originate from any arbitrary source (for example, manual logging). Their context fields are not set.
Log payload
The log payload contains the actual message (or information set) of the log entry. Unlike log files, a log payload is not limited to arbitrary text (but may still contain such) and can also contain complex types in a structured hierarchy (akin to JSON).
Supported data types include:
Strings
Numbers (integer and real numbers)
Boolean values
Arrays of strings, numbers, bytes, and Boolean values
Maps for the above types
While structured data can be useful in this context, first-party applications are still encouraged to use plain text for their logging.
For details, see the body specification in the OpenTelemetry documentation.