Logs are the oldest form of telemetry, and they remain the most detailed.

Every program ever written has needed a way to tell its owners what it is doing. The simplest way is to write a line of text whenever something noteworthy happens: a user signed in, a payment failed, a file could not be opened. These lines are called logs. Long before the words observability and tracing became popular, engineers solved problems by reading logs, and they still do, because logs capture the specific details of individual events that no summary can hold.

OpenTelemetry, often shortened to OTel, is an open-source, vendor-neutral standard for creating and moving telemetry. It covers three main kinds of data, called signals. Traces follow a request across services. Metrics summarize behavior as numbers over time. Logs record individual events with their details. Each signal answers a different kind of question, and the real power appears when all three are connected.

The Problem with Logs as They Are Usually Written

Traditional logs are written for humans to read, one line at a time. That works while one person reads one file on one machine. It breaks down when you run dozens of services across hundreds of machines producing millions of lines per hour. Nobody can read that much, so you must search it with tools, and tools struggle with free-form sentences. Structured logging is the solution to that struggle.

Before improving logs, we need to see why plain text logs cause pain.

A log record is a single entry that says something happened at a certain time. In its simplest form, it is one line of text beginning with a time, followed by a severity word such as information or error, followed by a human-readable sentence. For example, a line might say that a user with a particular name logged in from a particular address at a particular time. A person reads it easily. A computer sees only a string of characters.

Why Plain Text Becomes Painful

Structured logging records each event as a set of named fields rather than a free-form sentence.

Structured logging is the practice of writing each log record as organized data with named fields, instead of a single sentence of free text. A structured record still has a short human-readable message, but the important facts, such as the customer, the region, the amount, and the error type, are stored as separate labeled values. Because each fact has a name, tools can read them reliably without guessing.

Often, structured logs are written in a text format designed for data, with names and values paired up. But the format is not the point. The point is that the record has a stable shape that machines can understand. In OpenTelemetry, this shape is defined formally as the log data model, which we will explore soon.

The Two Layers of a Structured Log

A useful way to think about a structured record is as two layers. The first is a short, stable description of what happened, such as “payment failed”. The second is the set of facts that vary from event to event, such as which customer, which amount, and which provider. Keeping the description stable and the variable facts in separate fields is the heart of good structured logging, and it makes similar events easy to group.

What Makes a Good Structured Log?

A good structured log record has several qualities. It describes one thing that happened, rather than bundling many events together. It carries a clear, stable message that a stranger could understand. It includes the facts someone is likely to search for, each in its own named field. It states its severity honestly. And it is safe, meaning it contains no secrets or private personal information. When a record fails any of these tests, it is better rewritten than kept.

It also helps to remember the audience. Logs are not written only for the author. They are read by on-call engineers in the middle of the night, by support staff investigating a complaint, and by analysts studying trends. Clear names and values that a stranger can understand are far more valuable than clever shorthand that only the original developer remembers.

Logs sit on a spectrum, and most real systems have a mixture.

It helps to see logs as a spectrum rather than two boxes. At one end are completely free-form lines. At the other end are records with a strict, shared shape. In between are lines that follow a loose pattern, which tools can sometimes parse with rules, but not reliably.

flowchart LR
  A["Unstructured text line"] -->|"parsing rules"| B["Semi-structured pattern"]
  B -->|"extract fields"| C["Structured record"]
  D["Structured from the start"] --> C
        

Why Structure at the Source Is Best

You can convert unstructured lines into structured records later, using parsing rules in a processing tool. This is a very useful rescue technique for old software you cannot change. But every parsing rule is a guess about wording, and any change in the original sentence can silently break it. Writing structured records at the source avoids the guessing entirely, because the developer states exactly which value belongs in which field.

OpenTelemetry defines exactly which fields a log record has, so every tool agrees.

One of the most valuable things OpenTelemetry offers is a shared definition of what a log record looks like. This definition is called the log data model. Because every logging library, Collector, and backend that follows the standard agrees on these fields, a record created in one language can be understood by a tool written in another, without special translation.

flowchart TD
  L["Log record"] --> T["Timing: timestamp, observed timestamp"]
  L --> C["Correlation: trace ID, span ID"]
  L --> S["Severity: name and number"]
  L --> B["Body: the message or data"]
  L --> A["Attributes: facts about this event"]
  L --> R["Resource and scope: who produced it"]
        

Why Two Timestamps?

The first timestamp says when the event happened. The second says when the collection system saw it. Usually they are almost identical. But when logs are read from files, the original time may be missing, written in an odd format, or recorded by a machine with a wrong clock. Keeping both lets tools be honest about what they know and prevents silent confusion.

Severity helps you separate routine chatter from real trouble.

Every log record can carry a severity, which says how important or alarming it is. Different logging libraries use different words: some say warning, others say warn, some have a level called critical and others call it fatal. To end this confusion, OpenTelemetry defines a numbered scale from one to twenty-four, grouped into six bands. Every library’s levels are mapped onto this scale, so tools can compare logs from any source.

Why Both a Name and a Number?

The severity text keeps the original wording from the source library, which is helpful for people reading the logs. The severity number gives tools a single, comparable scale. A rule such as “keep everything at warn or above” is a simple numeric comparison that works for logs from every language. The bands also leave room within each band, so a library with several levels of debug detail can map them to different numbers inside the debug band.

The heart of structured logging is deciding which facts go in the message and which go in fields.

A log record has two places for information about the event: the body and the attributes. Understanding the difference is the single most important skill in structured logging.

The Body

The body is the main content of the record. For most application logs, it is a short human-readable message such as “payment failed” or “order shipped”. In OpenTelemetry the body is flexible: it can be simple text, but it can also be structured data itself, such as a collection of named values. This flexibility exists so that existing logs of many shapes can be carried faithfully. For application logging, the common and recommended pattern is a clear, stable message in the body.

The Attributes

Attributes are the named facts about this particular event. The customer’s plan tier, the region, the order amount, the error type, and the name of the payment provider are all attributes. Each has a key and a value, using the same attribute system you meet on spans and metrics. Because each fact has its own field, tools can filter on it, count by it, and compare it across thousands of records.

The Stable Message Idea

A powerful habit is to keep the message constant for a given kind of event and move every changing detail into attributes. Compare two ways of logging a failed payment. In the first, the message is built by pasting details into a sentence, so every record has different text. In the second, the message always says the same thing, and the details live in fields. With the second approach, you can find every payment failure by searching for one message, and you can break them down by provider or region instantly.

Shared names for common facts keep logs consistent across services.

Just as with traces and metrics, OpenTelemetry has semantic conventions for logs: a published, community-maintained dictionary of standard attribute names for common situations. If every team names the same idea differently, searching across services becomes impossible. A shared dictionary solves this, and tools that understand the dictionary can offer helpful features automatically.

Resource Attributes on Logs

Every log record is associated with a resource that describes who produced it. The service name, the service version, the deployment environment, the host, and in container platforms the pod and namespace are typical resource facts. They are recorded once for the source rather than repeated on every record, and backends combine them with the record when you search. Having consistent resource attributes across logs, traces, and metrics is what lets you jump between signals for the same service.

Naming Your Own Attributes

For facts specific to your business, create your own attributes while following the same style as the standard ones. Use lowercase, use dots to group related names, use underscores between words, and begin custom names with a prefix for your organization or application so they never collide with future standard names. Check the standard dictionary first, because reusing a standard name gives you free tool support.

A log that knows which request it belongs to becomes far more valuable.

The most exciting benefit of structured logging in OpenTelemetry is correlation. A trace is the story of one request, identified by a trace identifier, and each operation inside it has a span identifier. If a log record carries those two identifiers, you can jump from any log line directly to the trace that produced it, and from any span to every log written during it.

The remarkable part is that this usually happens automatically. When your application writes a log while a span is active, the OpenTelemetry logging integration reads the current trace and span identifiers from the surrounding context and attaches them to the record. The developer does not have to remember to include them or copy them by hand.

flowchart LR
  A["Request arrives"] --> B["Span starts: trace ID and span ID created"]
  B --> C["Application writes a log"]
  C --> D["Log record gets the same trace ID and span ID"]
  D --> E["Backend links the log to the trace"]
        

What This Makes Possible

You usually keep using your existing logging library; OpenTelemetry connects to it.

Developers often ask whether they must learn a brand-new logging interface. The answer is usually no. Most languages already have well-loved logging libraries, and teams have years of habits built around them. OpenTelemetry respects this. Instead of asking you to rewrite your logging calls, it provides a logs bridge that connects your existing library to the OpenTelemetry system.

The Moving Parts

Batching and Reliability

Sending every log record across the network immediately would slow the application and waste bandwidth. For that reason, the SDK normally places records in a buffer and sends them in batches at regular intervals, or when the buffer fills. This is efficient, but it means that if the application crashes suddenly, the most recent records still sitting in the buffer may be lost. Good configurations flush the buffer when the application shuts down normally, and keep the buffer size and interval at sensible values. If you cannot afford to lose even the last few records, writing to a file that a Collector reads can be a more forgiving approach.

Why a Bridge Is a Smart Design

This design gives you the best of both worlds. Your developers keep a familiar tool and do not need to change thousands of logging calls. Meanwhile, every record gains the standard OpenTelemetry shape, the shared resource information, and the automatic trace correlation. It also means you can switch backends without touching application code, because the destination is decided by configuration.

Structured at the Source with Existing Libraries

Most modern logging libraries already support attaching named values to a log call, rather than only a message. When you use that feature, the bridge carries those named values into the record’s attributes. This is the cleanest way to get structured logs: use your library’s structured features, and let the bridge deliver them.

There are two common ways for logs to leave your application, each with different trade-offs.

Logs can reach the Collector or backend in two broad ways. In the first, the application sends records directly using the OpenTelemetry SDK and bridge. In the second, the application simply writes structured lines to standard output or to a file, and a Collector running nearby reads them and converts them into OpenTelemetry records. Many organizations use both for different parts of their systems.

flowchart LR
  subgraph PathA
    A1["Application with bridge"] -->|"OTLP"| C1["Collector"]
  end
  subgraph PathB
    A2["Application writes to output or file"] --> F["Log file"]
    F -->|"read by file log receiver"| C2["Collector"]
  end
  C1 --> BE["Backend"]
  C2 --> BE
        

Why the File Path Is So Popular

In container platforms, the standard habit is for each application to write logs to standard output, and the platform stores them as files on the machine. A Collector running on each machine then reads those files. This approach is simple, requires no network setup in the application, and means that a crash does not lose logs that were already written. Its main weakness is that parsing and correlation must be handled with care, which is much easier if the lines were structured to begin with.

The Collector is the workshop where logs are cleaned up before they reach storage.

The OpenTelemetry Collector is a standalone program that receives telemetry, processes it, and sends it onward. For logs, it can do a lot of useful work in the middle. Because it is central, a fix made in the Collector benefits every service at once, without redeploying any application.

Receivers and Processors for Logs

On the receiving side, the file log receiver reads files and can apply parsing steps as lines are read. Other receivers handle syslog, system journals, message queues, and the standard OpenTelemetry protocol. On the processing side, general-purpose processors can add, rename, and delete attributes, a more flexible transform processor can change records based on conditions, a filter processor can drop records, and a batching processor groups records for efficient sending. The Collector can also route different logs to different destinations.

Some log records represent well-defined happenings, and OpenTelemetry gives them a name.

Ordinary log records are loosely defined: a developer writes whatever seems useful. But some happenings are important enough to define precisely, such as “a user clicked a button” or “a page finished loading”. OpenTelemetry treats these as events, which are log records that carry an event name and follow an agreed set of attributes for that kind of happening.

Giving events names and standard fields means every tool can recognize them and analyze them consistently. A browser-monitoring tool and a server-side tool could both understand the same kind of event, because they agree on its name and its fields.

Recording Errors Well

Errors are the most common reason people read logs, so recording them well matters. The standard approach uses dedicated attributes for the error type, the error message, and the stack trace. Because these have standard names, tools can group similar errors together, count how often each type occurs, and show the stack trace neatly formatted, even when logs come from services written in different languages.

Structure turns log searching from reading into asking questions.

The payoff of structured logging is felt when you sit in front of a log search screen during an incident. With structured fields, you can ask precise questions and get precise answers. Most tools let you do four things.

Logs as a Source of Metrics

Once logs are structured, counting them becomes easy, so some teams derive metrics from them, such as errors per minute by type. This is convenient, but remember that counting at the source with proper metrics is usually cheaper and more reliable than counting logs after the fact. Use logs for detail and metrics for ongoing trends.

Logs are usually the largest and most expensive signal, so manage them deliberately.

Logs tend to be the highest-volume signal in a system. A busy service can write thousands of lines every second, and every line has a cost: processing in the application, network bandwidth, storage, and indexing so it can be searched. Structured logs carry field names and values, which can make each record somewhat larger than a plain sentence, but the extra size usually pays for itself in searchability.

Controlling Volume

Logs and Trace Sampling

Traces are often sampled, meaning only a fraction are kept. Logs are normally not sampled in the same way, so you may see a log carrying a trace identifier for a trace that was not stored. That is expected, not a fault. The log is still valid and still useful; the identifier simply points to a trace that was not kept.

Logs are written by developers, read by many people, and kept for a long time, so they can leak secrets.

Logs are one of the most common places where sensitive information leaks by accident. A developer logs an entire request to help debugging, and it contains a password or a payment card number. Another logs a database statement with a real email address inside. Because logs are widely accessible and stored for months, the damage can be large and lasting. Structured logging helps here, because it lets you control precisely which fields are recorded, but it does not remove the risk by itself.

Layers of Protection

The strongest approach has several layers. First, design what gets logged so that sensitive values are never included. Second, use a clear allow-list of fields for sensitive areas of the code. Third, use the Collector as a safety net, with redaction, masking, and deletion rules that catch mistakes before logs leave your network. Fourth, restrict who can read logs in the backend, and set sensible retention so old data does not linger.

Seeing structured logging in familiar situations makes the ideas concrete.

Structured logging is one of the highest-value habits in observability, but it takes discipline.

Who Benefits from Better Logs?

Structured logs help far more people than the developers who write them. On-call engineers resolve incidents faster because they can filter precisely instead of reading walls of text. Support teams answer customer questions quickly by finding the exact record for a given order or request. Security teams look for unusual patterns, such as repeated failed sign-ins from one network. Product teams study how features are used. Auditors check that important actions were recorded with the right details. Because so many groups rely on the same logs, a small investment in consistent structure pays back many times over across the organization.

A Simple Adoption Path

You do not need to change everything at once. A gentle path starts by switching new code to your logging library’s structured features and a stable message style. Next, add the OpenTelemetry bridge so records carry the standard shape and trace identifiers. Then set consistent resource attributes across logs, traces, and metrics. After that, use the Collector to parse legacy logs, filter noise, and redact sensitive values. Finally, agree on a shared dictionary of attribute names and review it from time to time. Each step delivers value on its own.

A handful of habits prevent most problems.

Habits Worth Building

Mistakes to Avoid

Quick answers to the questions beginners ask most often.

A plain log is a sentence of free text. A structured log stores the important facts as separate named fields, so tools can search, filter, and count by those fields reliably.

Usually not. OpenTelemetry provides bridges or appenders that connect existing logging libraries to its system, so developers keep their familiar tools while records gain the standard shape.

The body is the main content, usually a short stable message. Attributes are named facts about this particular event, such as the region or error type. Keep the message stable and put variable details in attributes.

When a log is written while a span is active, the trace and span identifiers are attached to the record. A backend can then link the log to the trace, and the trace back to its logs.

OpenTelemetry maps every library’s levels onto a shared numeric scale from one to twenty-four, grouped into trace, debug, info, warn, error, and fatal bands, so logs from any source can be compared.

Yes. A Collector can read the software’s log files or syslog output, parse the lines into fields, and add resource information, giving legacy logs structure without code changes.

Both are valid. Direct export gives automatic trace correlation and no parsing. Files read by a Collector suit containers and legacy systems and survive short outages. Many organizations use both for different services.

Not normally. Logs are usually kept or filtered by severity and rules rather than sampled by trace. A log may therefore point to a trace that was not stored, which is expected.

An event is a log record that carries a name and follows an agreed set of attributes for a specific kind of happening, which lets tools recognize and analyze it consistently.

Design logging so that secrets and personal data are never recorded, prefer opaque identifiers, and add redaction and deletion rules in the Collector as a safety net. Also restrict access to logs and set sensible retention.

Structured logging means recording each event as a set of named fields rather than a loose sentence, so that people and tools can search, count, and compare logs reliably. OpenTelemetry gives these records a standard shape, called the log data model, with fields for time, severity, body, attributes, resource, and trace context. Existing logging libraries connect to it through bridges, logs can leave applications directly or through files read by a Collector, and the Collector can parse, enrich, filter, and redact on the way. The greatest prize is correlation: logs that carry trace and span identifiers connect seamlessly to the traces that produced them. Use stable messages, standard names, honest severity, careful privacy habits, and sensible volume controls, and your logs will become one of the most powerful tools you have.