A running program is a black box, and logs are the little windows we cut into it.

When a program runs on a server far away, nobody can watch it work. It does not have a face, and it cannot tell you what it is thinking. Yet people need to know what it did. Did the customer’s payment succeed? Why did a file fail to load? Which user triggered an error at three in the morning? Without any record, engineers are left guessing.

So programmers add small statements to their code that write a message whenever something interesting happens. A message may say that a user signed in, that a payment of a certain amount was accepted, that a database connection failed, or that the program is starting up. Each message is a log line. Collected together, these lines form the log, which is the diary of the program.

A short refresher on the big picture helps logs find their place.

OpenTelemetry, often called OTel, is an open-source project that defines how software describes its own behavior. It is vendor neutral, which means no single monitoring company owns it. It handles three kinds of data, called signals. Each signal answers a different kind of question, and logs are one of the three.

It is a structured record of one event, with a defined set of fields that every tool understands.

Let us define it carefully. A log, in the language of OpenTelemetry, is a recording of an event. Each individual entry is called a log record. A log record is not just a line of free text. It is a small structured package with named parts: a time, a severity level, a message body, a set of descriptive attributes, a description of the source, and optionally the identifiers of the trace and span that were active when the event happened.

The important idea is that OpenTelemetry gives every log record the same shape, no matter which programming language, framework or library produced it. A log from a Java service, a Python script and a Go program all arrive looking alike. Tools can then search, filter and connect them without learning many private formats.

Every log record is built from the same set of named parts.

OpenTelemetry defines a standard log data model, which is a list of the parts that a log record may have. Knowing these parts is like knowing the fields on a form. Once you know them, every log you meet becomes easy to read.

flowchart TD
  L["Log Record"] --> T["Timestamp and observed timestamp"]
  L --> S["Severity number and severity text"]
  L --> B["Body: the message"]
  L --> A["Attributes: extra details"]
  L --> R["Resource: who sent it"]
  L --> I["Instrumentation scope: which library"]
  L --> C["Trace ID, Span ID and flags: which request"]
        

Time sounds simple, but logs carry two different times for good reasons.

When did the event happen, and when did the system find out about it? These can be very different. Imagine a program that writes lines into a text file. A collector reads the file a few seconds later. The event time is written inside the line, but the collector sees the line only at a later moment. OpenTelemetry keeps both.

Every log record can say how important it is, using a shared scale.

Not all events deserve equal attention. A message that says the program started is routine. A message that says the database is unreachable is urgent. To tell them apart, logs carry a severity. OpenTelemetry defines a number from one to twenty-four, grouped into six familiar levels, and also allows the original text label that the source used, such as the word warning.

The number ranges exist because different logging libraries have different scales, and a shared number lets tools compare them. A warning from one library and a warning from another land in the same band, so a single filter such as show me everything at warning or above works across the whole company.

A good log separates the human sentence from the machine-friendly facts.

The body is the main content of the log record. Often it is a short human-readable sentence, such as a message saying a payment was declined. The body can also be structured data, for instance a set of named values, when the producer prefers that.

Attributes are the extra named details that describe the event. Instead of burying the customer’s region, the payment method and the amount inside a sentence, you attach them as separate attributes. This is what turns a log from a diary entry into searchable data.

This is the feature that makes OpenTelemetry logs special.

Traditional logs have a long-standing weakness. A busy service writes thousands of lines per second for thousands of customers, all mixed together. When one customer complains, it is hard to find the lines that belong to that customer’s request. OpenTelemetry solves this by letting every log record carry the Trace ID and Span ID of the work that was happening at the moment the log was written.

With these identifiers, a log is no longer a loose line. It is attached to a specific step of a specific request. Engineers can look at a slow trace and jump to the exact logs from that step, or look at an error log and jump to the whole trace around it.

flowchart LR
  T["Trace: one request, Trace ID T1"] --> S1["Span: check login, Span ID S2"]
  T --> S2["Span: charge card, Span ID S3"]
  S2 --> L1["Log: card declined, Trace ID T1, Span ID S3"]
  S1 --> L2["Log: login ok, Trace ID T1, Span ID S2"]
        

Two fields describe the origin of every log record.

A log without a source is a note found on the floor. OpenTelemetry therefore attaches two kinds of origin information. The resource describes the entity that produced the telemetry, such as the service name, its version, the host machine, the container and the cloud region. It is shared by everything that entity emits, so it is attached once and applies to every log, metric and trace.

The instrumentation scope describes the specific library or component that wrote the record, including its name and version. This helps when you want to separate logs written by your own code from logs written by a database driver or a web framework.

Developers usually keep the logging tools they already know.

Almost every programming language already has a favorite logging library, and most programs already use it. Asking everyone to rewrite their logging code would be unrealistic. OpenTelemetry takes a smarter route. It provides a Logs Bridge API, which is designed not for application developers to call directly, but for people who build the connectors, usually called appenders or handlers, that plug into existing logging libraries.

The idea is simple. The developer keeps writing logs the way they always did. A small bridge sits inside the logging library, receives each record, and converts it into an OpenTelemetry log record. During this step it also fills in the trace and span identifiers from the current context, which is how the magic link of the previous chapter appears without extra effort from the developer.

flowchart LR
  A["Application code writes a log with its usual logging library"] --> B["Log appender or bridge"]
  B --> C["OpenTelemetry Logger"]
  C --> D["Log record processor"]
  D --> E["Log record exporter"]
  E --> F["Collector or backend"]
        

A handful of cooperating parts move a log record from birth to export.

Inside an application, the OpenTelemetry SDK has a few pieces that work together for logs. Each has a small and clear job, and keeping them separate makes the system flexible.

Batching protects the application

Sending every log record over the network the instant it appears would be slow and wasteful. The common choice is a batch processor, which gathers records in a memory queue and sends them in groups from a background thread. The application continues without waiting. The trade-off is a small delay, and a risk that records still waiting in memory could be lost if the program crashes suddenly.

Not every log comes from code that uses an OpenTelemetry bridge.

Many logs are written to files or to the console by programs that know nothing about OpenTelemetry. Think of older software, third-party products, databases and operating systems. For these, the OpenTelemetry Collector, a standalone program that receives, processes and exports telemetry, can pick the logs up from the outside.

Raw logs are noisy, and the Collector is where they are shaped.

Logs are the largest of the three signals by volume. A busy company can produce terabytes of logs in a day, and much of it is repetitive or of little value. The Collector works as a pipeline with receivers, processors and exporters, and for logs its processors do several valuable jobs.

flowchart LR
  A["Receivers: files, network, platform streams"] --> B["Processors: parse, enrich, filter, mask"]
  B --> C["Exporter to fast search tool"]
  B --> D["Exporter to low-cost archive"]
  B --> E["Exporter to security tool"]
        

A named kind of log record is often called an event.

You may hear the word event used alongside the word log. In OpenTelemetry, an event is a log record that has a name, which identifies what kind of occurrence it is and defines the shape of its attributes. For example, a record named for a user completing a purchase would always carry the same set of attributes describing that purchase.

Plain logs are free-form. They are written for people to read and are often loosely structured. Events are more formal: the name acts like a type, so tools can count them, chart them and trust their fields. Both travel through the same log pipeline.

Each signal has strengths, and none replaces the others.

Logs often hold more secrets than anyone intended.

Because logs are written by developers in a hurry, they sometimes capture things that should never be stored: passwords, access tokens, card numbers, email addresses and full request bodies. Once these lines enter a searchable system and are copied to archives and vendors, they are very hard to remove. A careful approach treats the log pipeline as a place that must be protected.

Logs are easy to produce and expensive to keep.

Logging feels free when you write the line. The bill arrives later, because storage and search are priced by volume. A single chatty loop can produce millions of lines. Teams therefore manage log volume with a few simple habits.

Good habits and bad habits repeat across organizations.

Patterns that work

The strongest pattern is structured logging with context: short, clear messages, named attributes for each detail, and automatic trace identifiers. A second is log once at the right place, where the error is handled, instead of writing the same error at every layer it passes through. A third is process in the Collector, not in the application, so that masking, filtering and routing rules can change without redeploying code.

A short checklist that saves hours of pain later.

Every design choice has a price, and logs are no exception.

Balancing detail and cost

Every extra line gives more detail and costs more money. Too little logging leaves engineers blind during an incident. Too much logging buries the evidence and inflates the bill. The skill lies in logging the events that explain behavior, in a structured way, and trusting metrics and traces to carry the rest of the load.

Seeing how teams use OpenTelemetry logs makes the ideas concrete.

It is a structured, time-stamped record of an event, called a log record, carrying severity, a body, attributes, a description of its source, and optionally the identifiers of the trace and span it belongs to.

A normal line is just text. An OpenTelemetry log record has defined named fields, so tools can filter by severity, source or trace without guessing from text.

Usually no. A logging bridge or appender plugs into your existing logging library and converts records into OpenTelemetry log records automatically.

It is the part of OpenTelemetry meant for building connectors into existing logging libraries. It is intended for appender authors, not for everyday application code.

Severity says how serious the event is. OpenTelemetry uses numbers from one to twenty-four, grouped into trace, debug, info, warn, error and fatal bands.

One records when the event happened and the other records when the system observed it. They can differ, for example when a collector reads a file later.

Each log record can carry the Trace ID and Span ID that were active when it was written, so you can jump from a trace to its logs and back.

An event is a log record that has a name identifying its kind and a defined set of attributes. Plain logs are more free-form.

Yes. The Collector can read log files, parse lines into fields, enrich them with labels and forward them, even from software that knows nothing about OpenTelemetry.

They are the highest-volume signal, and storage and search are usually priced by volume. Filtering, tiering and using metrics for counting help control cost.

Never write them in the first place, review log statements, and use Collector processors to mask or remove sensitive fields as an extra safety net.

Use a metric. A counter is far cheaper than a log line for every request. Keep logs for events that need explanation.

Likely the program ended before the batch processor sent its final group. Flush and shut down the logging pipeline before exiting.

We began on the bridge of a ship, where the captain’s logbook records the story of a voyage line by line. A log in OpenTelemetry is that same diary, given a modern, standard shape. Each entry is a log record with a time, a severity, a body, attributes, a description of its source and, ideally, the identifiers of the trace and span it belongs to. Existing logging libraries feed OpenTelemetry through bridges, the Collector gathers logs from files and platforms, cleans and masks them, and routes them to the right destinations. Used together with metrics and traces, logs complete the picture: metrics notice, traces locate, and logs explain.