Before we define a log record, let us see the mess it was invented to clean up.

What is a log?

A log is a message that a program writes to describe something that happened. “User signed in.” “Payment failed.” “Disk almost full.” Programmers have written logs since the earliest days of computing because logs are simple, human-friendly and available everywhere. When something breaks at three in the morning, logs are often the first place an engineer looks.

The trouble with free-form text

For most of history, every program has written its logs in its own style. One writes the date first, another writes the severity first, a third writes everything in capital letters. One uses a dash as a separator, another uses a pipe. Some write plain sentences, and some write structured pieces of data. When a company runs hundreds of services written by dozens of teams, its logs become a pile of mismatched styles.

Searching this pile is painful. To find all errors, an engineer must know that one service says “ERROR”, another says “Err”, another says “SEVERE”, and another says “level three”. To find which logs belong to one customer request, they must guess from timestamps. Tools must be taught each style separately, using fragile text patterns that break whenever someone changes a message.

Logs are one member of a family of three, so let us meet the family.

OpenTelemetry, often shortened to OTel, is an open-source project that defines a common way for software to describe its own behaviour. The data it describes is called telemetry, and it comes in three main kinds called signals.

The three signals are designed to work together. A metric raises the alarm, a trace shows where, and a log often explains why. For this teamwork to function, they must share common labels and identifiers. The log record is the piece that lets logs join that team.

A plain definition first, then the reasons behind each word.

A log record in OpenTelemetry is a single, structured entry that describes one event at one point in time. It is made of a set of named fields, such as when the event happened, how serious it was, what the message said, who produced it, and which trace it belongs to. The standard that defines these fields is called the log data model.

That definition has three important ideas inside it.

Every log record is built from the same handful of fields.

Learning these fields is the heart of this guide. Once you know them, you can read any OpenTelemetry log from any system. We will look at them in groups.

Group 1: When did it happen?

Group 2: How important is it, and what does it say?

Group 3: Which request does it belong to?

Group 4: Who wrote it, and what else is known?

flowchart TD
  LR["Log Record"] --> W["When: Timestamp, Observed Timestamp"]
  LR --> I["Importance: Severity Number, Severity Text"]
  LR --> C["Content: Body, Event Name"]
  LR --> T["Trace link: Trace ID, Span ID, Trace Flags"]
  LR --> O["Origin: Resource, Instrumentation Scope"]
  LR --> A["Detail: Attributes"]
        

Having two times sounds odd, but it solves a real problem.

Imagine a security camera that records a burglary at 2 a.m., but the footage is only uploaded to the cloud at 9 a.m. If investigators looked only at the upload time, they would believe the burglary happened at nine. They need to know both: when it happened, and when the system first saw it.

Logs have the same issue. A program may write a line to a file at 2 a.m. A collection tool may only read that file at 2:05 a.m. The first is the Timestamp, the moment of the event as the source reports it. The second is the Observed Timestamp, the moment the record entered the telemetry system.

Everyone agrees that an error is worse than a note, but they use different words for it.

Logging libraries each invented their own severity words. Some say “Debug”, “Info”, “Warning” and “Error”. Some say “Fine”, “Config” and “Severe”. Some use numbers where a larger number means worse, and others use numbers where a smaller number means worse. To compare logs across systems, a translation is needed.

OpenTelemetry solves this with two fields. The Severity Number is a standard scale from one to twenty-four, grouped into six families. The Severity Text keeps the original word, so nothing is lost in translation.

Why four numbers in each family?

Within each family, the four numbers allow finer shades. The first number in a family is the plain level, and higher numbers mean slightly more severe versions of the same level. A source that has two kinds of warnings, one mild and one stronger, can map them onto two different numbers within the warning family. For most beginners, it is enough to remember the six families and their order.

Filtering by severity

Because severity is a number, tools can filter easily: “show me everything at error level or above” becomes “show records with a severity number of seventeen or more”. Systems can also decide to keep only certain levels in expensive storage and send the rest to cheaper storage.

The body is where the actual content of the log lives.

The Body is the main payload of a log record. In the simplest case, it is a plain piece of text, such as “Payment declined by the bank”. But OpenTelemetry also allows the body to hold structured data: a list, or a set of named values. This flexibility lets the model carry logs from very different sources.

Structured logs are better logs

Compare two ways of recording the same event. In the first, the program writes a sentence: “Customer in Berlin paid 40 euros using a card”. In the second, it records a short message “Payment completed” with attributes for city, amount, currency and method. To count payments per city from the first form, a tool must read and parse sentences, and a small wording change breaks everything. From the second form, it simply groups by the city attribute.

This is the feature that turns logs from isolated notes into pieces of a bigger story.

Suppose a customer’s checkout fails. Your logs contain millions of lines from dozens of services. Which ones belong to this customer’s request? Without a link, you must guess using time and luck. With OpenTelemetry, when a log is written while a span is active, the log record automatically carries the Trace ID and Span ID of that span.

Now the investigation is easy. In a tracing tool, you find the failed trace, note its trace ID, and ask the log tool for every record carrying that ID. You immediately see the messages written by every service that touched that request, in order. You can also go the other way: start from an error log, read its trace ID, and open the full trace to see the surrounding story.

sequenceDiagram
  participant U as Customer
  participant W as Web Service
  participant P as Payment Service
  U->>W: Click Buy
  Note over W: Span A active, trace ID shared
  W->>W: Writes log with trace ID and span A
  W->>P: Call payment with trace context
  Note over P: Span B active, same trace ID
  P->>P: Writes error log with trace ID and span B
  P-->>W: Failure reply
  W-->>U: Error page with trace reference
        

Two layers of context explain the origin of every log record.

A log message such as “connection timed out” is nearly useless without knowing which service wrote it and where it was running. OpenTelemetry attaches this information in two layers, and it does so once for many records instead of repeating it inside each one.

Why resource matters so much

The resource is what lets a tool say “show me all error logs from the checkout service in production”. Without a clear service name and environment, logs from your test system and your live system get mixed together, and the owner of each log is a mystery. Because metrics, traces and logs all carry the same resource, you can line up everything from one service under one name.

The extra labels that make logs searchable and meaningful.

Attributes

An attribute is a pair made of a name and a value. It adds detail to one log record. For a log about a failed web request, useful attributes might include the route, the status code and the name of the region. Attributes are what let you ask “show me all errors for the checkout route in the Mumbai region”.

Following common names

OpenTelemetry publishes semantic conventions, which are agreed names for common attributes: for web requests, databases, messaging, cloud platforms and exceptions. When you use these standard names, any tool can recognise them. For example, if an exception is recorded using the standard attribute names for exception type, message and stack trace, a backend can group similar errors together automatically.

Event names

Not all log records are free-form messages. Some describe a well-defined occurrence, such as “a user signed in” or “a device was rebooted”. For these, the Event Name field gives the occurrence a stable, machine-friendly name. The record then behaves like a small structured event, with attributes defined for that particular name. This idea lets teams build consistent, queryable events on top of the log signal.

Developers keep using the logging tools they already know.

Most programming languages already have popular logging libraries, and teams have written millions of log statements using them. It would be unreasonable to ask everyone to rewrite all of that. So OpenTelemetry takes a different approach for logs than for traces and metrics. It provides a Logs Bridge API, and its main users are not application developers, but the people who build appenders or bridges for existing logging libraries.

An appender is a small plug-in for a logging library. Whenever your code writes a log through its familiar library, the appender catches the entry, converts it into an OpenTelemetry log record, and hands it to the OpenTelemetry SDK. Your application code does not change.

flowchart LR
  A["Your code writes a log with a familiar library"] --> B["Appender or bridge converts it"]
  B --> C["Logger creates a log record"]
  C --> D["Log record processor batches records"]
  D --> E["Log exporter sends over OTLP"]
  E --> F["Collector"]
  F --> G["Log backend and search tool"]
        

The pieces inside the SDK

Logs can reach OpenTelemetry in more than one way.

Logs are special because many applications already write them to files or to the console, and many systems do not use OpenTelemetry at all. OpenTelemetry therefore supports two main roads.

Road 1: Send logs directly from the application

The application uses an appender and the SDK, and sends records over OTLP to a Collector or backend. Because the SDK creates the log record directly, it can attach the trace ID and span ID perfectly at the moment of writing, and it knows the resource precisely. This road gives the richest and most accurate records.

Road 2: Write to files and let the Collector read them

The application writes logs the way it always has, to a file or to the console, and a Collector running beside it reads the files. A receiver designed for file reading follows the file as it grows, splits the text into separate entries, extracts fields such as time and severity, and converts each entry into a log record. This road requires no change to the application and works for software you cannot modify, such as databases and third-party tools.

flowchart LR
  A1["App with OpenTelemetry SDK"] -->|"OTLP"| COL["Collector"]
  A2["Legacy app writing log files"] --> F["Log files on disk"]
  F -->|"File receiver reads and parses"| COL
  A3["Database and other software"] --> F
  COL --> P["Add resource, filter, redact, batch"]
  P --> B["Log backend"]
        

The Collector is the workshop where raw logs become clean, safe, useful records.

The OpenTelemetry Collector is a separate program that receives telemetry, processes it, and forwards it. For logs, it offers several valuable abilities. Think of the Collector as the central sorting office for all your log records.

Each signal is strongest when it can point to the others.

The real benefit of the OpenTelemetry log record is not that logs look prettier. It is that logs can finally join an investigation alongside traces and metrics, using shared identifiers and shared context.

A typical investigation

More logs are not always better logs.

Because logging is easy, many teams log far too much, and then pay for storage and search of lines nobody ever reads. Others log too little, and are blind during an incident. A few simple guidelines help find the balance.

Logs are one of the most common places where sensitive data leaks.

Because logs are written by programmers in a hurry, they often capture more than intended. A debug line that prints a whole request might include a password. An error message might include a customer’s email. Once written, a log may be copied to many tools and kept for months or years. Treat logs as sensitive data.

Habits that keep logs useful and affordable.

Good habits

Mistakes to avoid

A shared data model brings real benefits and a few limits.

Logs, traces and metrics compared

Picture how different teams use log records every day.

You do not need to learn everything at once.

It is one structured log entry in the standard OpenTelemetry shape. It holds fields for when the event happened, how serious it was, what it said, who produced it, and which trace it belongs to.

A log line is usually a single piece of text in whatever style the program chose. A log record organises the same information into named fields with agreed meanings, so any tool can read it without guessing.

The Timestamp says when the event happened, according to the source. The Observed Timestamp says when the telemetry system first saw it. Together they help you tell whether a delay is in the application or in collection.

It is a standard scale from one to twenty-four, grouped into trace, debug, info, warn, error and fatal families. It lets tools compare and filter logs from systems that use different severity words, while the severity text keeps the original word.

When a log is written while a span is active, the log record carries that span’s trace ID and span ID. You can then search logs by trace ID, or open the trace from a log’s identifiers.

No. OpenTelemetry provides bridges, also called appenders, for popular logging libraries. They convert your existing log calls into log records automatically, so your code stays the same.

It is the main content of the record. It can be simple text, or it can be structured data with named values. Many teams keep the body short and stable, and put changing details in attributes.

Yes. A file-reading receiver follows log files as they grow, splits them into entries, extracts fields such as time and severity, and converts each entry into a log record. This works even for software you cannot modify.

It is an optional field that gives a stable name to a well-defined occurrence, such as a sign-in. It turns a log record into a small structured event with attributes that belong to that name.

Use metrics. A counter is cheap, fast and designed for rates. Logs are for the details of individual events. Counting log lines to produce numbers is slow and expensive.

Do not log secrets or personal data in the first place, review code that prints whole requests, and add redaction rules in the Collector as a safety net. Also limit who can read logs and set sensible retention periods.

Yes. Metrics tell you that something changed, traces show where, and logs often explain why, in readable detail. The three signals are designed to work together, each filling gaps the others leave.

A log record in OpenTelemetry is the standard shape of one log entry. Instead of a loose line of text, it organises information into named fields: a timestamp and an observed timestamp, a severity number and text, a body, an optional event name, trace and span identifiers, a resource, an instrumentation scope and attributes. This common shape lets logs from any language and tool be searched, filtered and compared in the same way, and lets them join traces and metrics through shared identifiers and context. Existing logging libraries feed the pipeline through bridges, so code rarely needs rewriting, and a Collector can parse, enrich, filter, redact and route records, including those read from plain files. Keep messages stable, put details in attributes, use severity honestly, attach trace context, protect sensitive data, and use metrics for counting, so your logs remain useful, safe and affordable.