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.

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.