Logs

A log is a timestamped text record, either structured (recommended) or unstructured, with metadata. Of all telemetry signals, logs have the biggest legacy. Most programming languages have built-in logging capabilities or well-known, widely used logging libraries. Although logs are an independent data source, they may also be attached to spans. In OpenTelemetry, any data that is not part of a distributed trace or a metric is a log. For example, events are a specific type of log. Logs often contain detailed debugging/diagnostic info, such as inputs to an operation, the result of the operation, and any supporting metadata for that operation.

For traces and metrics, OpenTelemetry takes the approach of a clean-sheet design, specifies a new API, and provides full implementations of this API in multiple language SDKs.

OpenTelemetry’s approach with logs is different. Because existing logging solutions are widespread in language and operational ecosystems, OpenTelemetry acts as a “bridge” between those logs, the tracing and metrics signals, and other OpenTelemetry components. In fact, the API for logs is called the “Logs Bridge API” for this reason.

The logs specification contains more details on this philosophy.

To understand how logging in OpenTelemetry works, let’s look at a list of components that will play a part in instrumenting our code.

Log Appender / Bridge

As an application developer, the Logs Bridge API should not be called by you directly, as it is provided for logging library authors to build log appenders / bridges. Instead, you just use your preferred logging library and configure it to use a log appender (or log bridge) that is able to emit logs into an OpenTelemetry LogRecordExporter.

OpenTelemetry language SDKs offer this functionality.

Logger Provider

Part of the Logs Bridge API and should only be used if you are the author of a logging library.

A Logger Provider (sometimes called LoggerProvider) is a factory for Loggers. In most cases, the Logger Provider is initialized once and its lifecycle matches the application’s lifecycle. Logger Provider initialization also includes Resource and Exporter initialization.

Logger

Part of the Logs Bridge API and should only be used if you are the author of a logging library.

A Logger creates log records. Loggers are created from Log Providers.

Log Record Exporter

Log Record Exporters send log records to a consumer. This consumer can be standard output for debugging and development-time, the OpenTelemetry Collector, or any open source or vendor backend of your choice.

Log Record

A log record represents the recording of an event. In OpenTelemetry a log record contains two kinds of fields:

  • Named top-level fields of specific type and meaning
  • Resource and attributes fields of arbitrary value and type

The top-level fields are:

Field NameDescription
TimestampTime when the event occurred.
ObservedTimestampTime when the event was observed.
TraceIdRequest trace ID.
SpanIdRequest span ID.
TraceFlagsW3C trace flag.
SeverityTextThe severity text (also known as log level).
SeverityNumberNumerical value of the severity.
BodyThe body of the log record.
ResourceDescribes the source of the log.
InstrumentationScopeDescribes the scope that emitted the log.
AttributesAdditional information about the event.

For more details on log records and log fields, see Logs Data Model.

Language Support

Logs are a stable signal in the OpenTelemetry specification. For the individual language specific implementations of the Logs API & SDK, the status is as follows:

LanguageLogs
C++Stable
C#/.NETStable
Erlang/ElixirExperimental
GoIn development
JavaStable
JavaScriptExperimental
PHPStable
PythonExperimental
RubyIn development
RustAlpha
SwiftIn development

Specification

To learn more about logs in OpenTelemetry, see the logs specification.