Logs | OpenTelemetry

A log is a timestamped text record, either structured (recommended) or unstructured, with optional 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.
OpenTelemetry provides a Logs API and SDK for producing log records, and language SDKs and logging bridges to integrate with existing logging frameworks. Logs are anything you send through a Logging Provider, and events are a special type of logs. Not all logs are events, but all events are logs. The Logs API is public and can be used directly by application code or indirectly via existing logging libraries and bridges.
OpenTelemetry is designed to work with the logs you already produce, offering tools to correlate logs with other signals, add contextual attributes, and normalize different sources into a common representation for processing and export.
The OpenTelemetry Collector provides several tools to work with logs:
The first step in adopting OpenTelemetry frequently involves deploying a Collector as a general-purposes logging agent.
In applications, OpenTelemetry logs are created with any logging library or built-in logging capabilities. When you add autoinstrumentation or activate an SDK, OpenTelemetry will automatically correlate your existing logs with any active trace and span, wrapping the log body with their IDs. In other words, OpenTelemetry automatically correlates your logs and traces.
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:
OpenTelemetry accepts any log format, but not all formats are equally useful for analysis. The following section explains the differences between structured, semistructured, and unstructured logs. Important: a log encoded as JSON is not automatically “structured” in the sense of having a stable schema —it may be semistructured. Structured logs imply a consistent schema or well-defined typed fields that downstream processing can reliably depend on.
A structured log is a log with a defined, consistent schema or typed fields that downstream systems can reliably parse and interpret. The textual encoding can be JSON, protobuf, or another format, but what makes a log structured is the presence of a stable schema (field names, types, and semantics), not merely that it is valid JSON. For example, a structured JSON log might look like:
and for infrastructure components, Common Log Format (CLF) is commonly used:
It is also common to encounter hybrid or extended formats (for example, CLF fields combined with a trailing JSON blob).
In those cases, parse or extract the parts you need into a normalized record so downstream tooling can analyze them consistently. The filelogreceiver in the OpenTelemetry Collector provides helpers to parse mixed formats.
Structured logs are preferred in production because their stable schema makes them straightforward to validate, parse, correlate with traces and metrics, and analyze at scale.
Unstructured logs are logs that don’t follow a consistent structure. They may be more human-readable, and are often used in development. However, it is not preferred to use unstructured logs for production observability purposes, since they are much more difficult to parse and analyze at scale.
Examples of unstructured logs:
It is possible to store and analyze Unstructured logs in production, although you may need to do substantial work to parse or otherwise pre-process them to be machine-readable. For example, the above three logs will require a regular expression to parse their timestamps and custom parsers to consistently extract the bodies of the log message. This will typically be necessary for a logging backend to know how to sort and organize the logs by timestamp. Although it’s possible to parse unstructured logs for analysis purposes, doing this may be more work than switching to structured logging, such as via a standard logging framework in your applications.
Semistructured logs include machine-readable key/value pairs or delimited fields but do not guarantee a stable schema across emitters. Examples include key=value logging (shown below) or JSON blobs where field names and types vary between messages. Semistructured logs are often easier to parse than unstructured logs but may still require processing and normalization before analysis.
Example of a semistructured log:
Semistructured logs may require mapping and type coercion during ingestion to be fully useful for downstream analysis.
A common question is whether application code should check if logging is enabled before making a logging call, for example:
In most cases this check is unnecessary and not recommended. OpenTelemetry SDKs are designed to be efficient – the invocation of the logging API has minimum overhead when the logger is not enabled. Making an extra call to logger.Enabled decreases performance and makes your code harder.
The Enabled API is useful only when evaluating the arguments passed to the logging call is itself expensive, and you want to avoid that cost when the logger is not enabled. For example, if the body or an attribute must be fetched from a database or computed through an expensive operation:
Only guard expressions that are free of side effects, since the guarded code runs only when logging is enabled. Guarding code that has side effects, or that other logic depends on, makes your application’s behavior depend on the logging configuration, which is usually a source of subtle bugs.
Even then, keep in mind that the result of Enabled is not static: it can change over time as configuration changes, so it should be evaluated per log record and not cached.
For normative API guidance, see Logs API specification.
The following lists of concepts and components power OpenTelemetry’s logging support.
As an application developer, the Logs Bridge API should not be called by you