Breaking down common terminologies in OpenTelemetry

The first time someone mentioned “context propagation” and “baggage” in the same sentence, I wondered if we were talking about distributed systems or airport logistics. If you’re new to OpenTelemetry entirely, you might want to check out my previous post explaining what OpenTelemetry is before diving into this blog post. But if you’ve got the basics down and just need to decode the jargon, you’re in the right place.

Lets recap on telemetry and observability

Think of telemetry like your car’s dashboard. You’ve got your speedometer, fuel gauge, engine temperature warning light that makes your heart skip a beat — all automatically collecting data about what’s happening under the hood. OpenTelemetry does the same thing for your applications, except instead of “check engine,” you get “your API is slow.”

Observability is what happens when you actually look at that dashboard and understand what it’s telling you. It’s the difference between having a speedometer and knowing that 85 mph in a school zone is probably not ideal.

These are the three observability pillars everyone talks about, and for good reason.

Traces are like following breadcrumbs through your system. Picture this: you order a pizza online. There’s the web request when you hit “order,” the database lookup to check if pepperoni is in stock, the payment processing that hopefully doesn’t decline your card, and the notification to the kitchen. Each of these steps is a span, and the whole journey from “I want pizza” to “pizza confirmed” is your trace.

Metrics are the numbers that keep you up at night. Response times, error rates, memory usage, basically anything you can slap on a graph and stare at during incidents while questioning your life choices.

Logs are what they’ve always been , those timestamped messages that either tell you everything’s fine or that something is very, very wrong. “User logged in” versus “Database is on fire”. I hope you get the picture.

Now lets get to the terminologies.

Instrumentation is just a fancy word for “the code that actually generates the telemetry.” You can write it yourself (manual instrumentation) or use libraries that do it for you (automatic instrumentation). Guess which one most of us prefer? We'll see in my subsequent blog posts.

A span represents a single unit of work and I'd like to think of it as one task in your application’s to-do list. “Query the database,” “call the payment API,” “send an email” where each gets its own span. Spans have relationships. A parent span might be “process order,” and its children could be “validate payment,” “check inventory,” and “update database.” It’s like a family tree, but for code execution.

Context propagation sounds intimidating, but it’s really just making sure that when your request bounces from service A to service B to service C, they all know they’re part of the same conversation. Without it, you’d have a bunch of disconnected spans that tell you nothing useful.

Baggage (yes, that’s the actual term) is extra key-value data that gets carried along with your trace context. Think of it as stuffing extra snacks in your carry-on information that might be useful later but isn’t essential for the basic trace to work.

The Collector is where we often overcomplicate things. It’s really just a middleman that takes your telemetry data, maybe cleans it up, adds some tags, or routes it to different destinations. Think of it as a really smart postal worker who can sort, filter, and forward your mail based on whatever rules you set up.

Receivers accept data coming in (from your applications), processors do stuff to that data (filtering, adding metadata, sampling), and exporters ship it off to your observability platform of choice.

Sampling is about being selective with what traces you keep, because storing every single request from a busy application would bankrupt your cloud bill and probably crash your storage system.

Head-based sampling makes decisions at the start of a trace — like deciding to keep every 10th request. Tail-based sampling waits until the trace is complete before deciding whether to keep it which is useful for catching all the errors but letting most of the boring successful requests go.

The terminology might seem overwhelming at first, but once you start using these concepts in practice, they’ll start making sense. It’s like learning a new language, awkward at first, but eventually you’ll be throwing around terms like “context propagation” and “baggage” like you’ve been doing it for years.

Now that you’ve got the vocabulary down, the real fun begins, actually implementing this stuff. But that’s a story for another blog post. For now, you’re armed with enough terminology knowledge to at least nod confidently in meetings when someone mentions distributed tracing.

Happy Tracing!

Thanks for reading!