What Are Span Attributes in OpenTelemetry?
Span attributes are the labels you attach to a unit of work so that a trace tells you not just what happened and how long it took, but also who, what, where, and why. This guide explains them from zero: what they are, how they are named and typed, how they travel, and how to use them wisely.
Imagine you work at an airport baggage desk and a suitcase arrives with no tag on it. You know it exists, and you can see how long it has been sitting on the belt, but you have no idea whose it is, where it came from, or where it is supposed to go. Now imagine the same suitcase with a clear tag showing the owner, the flight number, and the destination. Suddenly the suitcase is useful. In OpenTelemetry, a span without attributes is the untagged suitcase, and a span with good attributes is the tagged one. Learning how to attach the right tags is one of the most valuable skills in observability.
1The Big Picture: Why Traces Need Detail
Timing alone rarely explains a problem; context does.
Modern applications are built from many cooperating parts. A single click on a website can trigger work in a web server, a login service, a product catalog, a payment provider, and several databases. When something is slow or broken, engineers need to follow the request across all of those parts. The tool that makes this possible is distributed tracing, and the basic building block of a trace is the span.
A trace shows you a timeline of spans, each one a measured piece of work. That timeline can instantly tell you that the payment step took four seconds. But a timeline alone cannot tell you whether the slow payments were all from one country, one payment method, one customer type, or one software version. To answer those deeper questions, each span needs to carry descriptive details. Those details are called attributes.
Think of a doctor’s appointment record. The time slot tells you when the visit started and ended, much like a span’s timing. But the useful information is in the notes: the patient’s symptoms, the tests ordered, and the treatment given. Span attributes are the notes written on the appointment record.
Where Attributes Fit in the Telemetry Story
OpenTelemetry is an open-source, vendor-neutral standard for creating and moving telemetry data such as traces, metrics, and logs. Attributes appear in all of these signals, but this guide focuses on the ones attached to spans. Understanding them will also make attributes on metrics and logs much easier to grasp later, since the same ideas apply.
The word attribute in OpenTelemetry always means a key paired with a value. You will see this same pattern again and again, so learning it once pays off everywhere.
2First, What Is a Span?
You cannot understand a span’s labels until you understand the span itself.
A span represents one operation: a single piece of work with a clear beginning and end. Handling a web request is a span. Running a database query is a span. Calling another service is a span. Spans can contain other spans, forming a parent-child tree, and the whole tree for one request is called a trace.
Every span carries a small, fixed set of built-in parts. Attributes are only one of them, so it helps to see the full picture so you can tell which part is responsible for which job.
Name
A short label for the operation, such as the kind of request or action being performed.
Identity
A trace identifier shared by the whole request and a span identifier unique to this operation, plus a link to the parent.
Timing
A start time and an end time, from which the duration is calculated.
Kind
The role of the span, such as handling an incoming request, making an outgoing call, or simply doing internal work.
Status
Whether the operation succeeded, failed, or was left unset.
Attributes
Key-value details that describe this particular operation. This is our topic.
Events
Time-stamped notes about things that happened during the span, such as an exception being thrown.
Links
References to other spans that are related but are not parents, such as a batch job that handles many messages.
flowchart TD
T["Trace: one whole request"] --> S1["Span: handle web request"]
S1 --> S2["Span: check login"]
S1 --> S3["Span: load cart"]
S3 --> S4["Span: database query"]
S1 --> S5["Span: call payment service"]
The span’s built-in parts answer standard questions such as when, how long, and did it work. Attributes answer the open-ended questions that are specific to your system.
3What Is a Span Attribute?
A span attribute is one labeled piece of information attached to one span.
A span attribute is a key-value pair attached to a span to describe the operation it represents. The key is the name of the label, and the value is the information itself. For example, a span representing a web request might carry an attribute whose key names the request method and whose value says it was a read request, another whose key names the response code and whose value says the request succeeded, and another whose key names the route and whose value shows which page was requested.
Why does this exist? Because the span’s built-in parts cannot possibly anticipate every detail that matters to every application. A bank cares about account types and transaction categories. A video platform cares about resolution and device models. A logistics company cares about warehouses and carriers. Attributes give every team a flexible, standard way to attach exactly the details they need, without changing the span structure itself.
A span attribute is like a sticky note on a photograph. The photograph is the span, a snapshot of one moment of work. Each sticky note adds one fact: where it was taken, who was in it, what the occasion was. You can add as many sticky notes as you need, up to a sensible limit, and anyone looking at the photo later can read them.
Why Attributes Are So Powerful
The real power of attributes shows up when you look at many spans together. Observability tools let you filter, search, and group spans by their attributes. This lets you ask questions such as “show me all slow checkout spans where the customer is on the premium plan” or “compare error rates between version two and version three of the payment service”. Without attributes, you could see that something was slow, but never discover the pattern behind it.
What Makes a Good Attribute?
Not every piece of information deserves to become an attribute. A good attribute has three qualities. First, it is useful: someone can imagine a real question that it helps answer, such as which region, which version, or which kind of customer. Second, it is stable in meaning: the same key always means the same thing in every service, so results can be combined safely. Third, it is safe: it does not expose secrets or private personal information. When a candidate fact fails any of these three tests, it is better left out.
It also helps to think about who will read the attribute. Attributes are not written for the computer alone; they are read by on-call engineers at three in the morning, by support staff investigating a complaint, and by analysts studying trends. Names and values that are clear to a stranger are far more valuable than clever shorthand that only the original author understands.
Attributes describe what a span did. They do not change how the span behaves, and they do not affect whether the operation succeeds. They are purely descriptive information for people and tools that analyze the trace later.
4The Anatomy of an Attribute: Keys, Values, and Types
Every attribute follows the same simple rules, which makes them predictable.
Keys: The Names
An attribute key is a non-empty piece of text that names the label. Within a single span, each key can appear only once. If you set the same key a second time, the new value replaces the old one. Keys are case sensitive, so two keys that differ only in capital letters are treated as different keys, which is a common source of confusion. By strong convention, keys are written in lowercase, with dots separating the levels of a namespace and underscores separating words inside a level.
Values: The Information
An attribute value can be one of a small number of simple types. This limited list is intentional. It keeps data easy to store, transport, and search across many different tools and languages.
| Value type | What it holds | Typical example |
|---|---|---|
| String | Text | A region name or a plan name |
| Boolean | True or false | Whether the cache was used |
| Integer | A whole number | Number of items in a cart |
| Floating-point number | A number with decimals | A discount ratio |
| Array of one type | A list where every item has the same type | A list of product categories |
Notice what is not on the list. A value cannot be a complex nested object, and an array should hold items of one type only. If your data is naturally nested, the usual approach is to flatten it into several attributes with a shared prefix in their keys, such as one attribute for the order’s item count and another for its currency. Empty or missing values are also best avoided rather than stored as placeholders, since they add noise without information.
A form with typed boxes is easier to process than a free-form letter. The attribute types are like the boxes on a form: a text box, a yes-or-no tick box, a number box. Because there are only a few kinds of box, every office that receives the form knows exactly how to read it.
Why the Type Matters
Choosing the right type is not just tidiness. A backend can calculate averages, maximums, and ranges only for numbers. If you store the number of items in a cart as text, you lose the ability to ask for the average cart size. Likewise, a true-or-false field stored as the words “yes” and “no” invites inconsistency, because another team might use “Y” and “N” instead. Pick the natural type for the data and stay consistent.
Storing numbers as text. It looks harmless, but you lose arithmetic, sorting by magnitude, and range filters. Keep numbers numeric whenever they truly are numbers.
5Span Attributes versus Resource Attributes
Some details describe the operation; others describe the thing that performed it.
New learners often mix up two kinds of attributes because they look identical. Both are key-value pairs. The difference is what they describe. Span attributes describe one specific operation. Resource attributes describe the entity that produced the telemetry, such as the service, the machine, or the container, and they stay the same for everything that entity produces.
| Question | Span attributes | Resource attributes |
|---|---|---|
| What do they describe? | One particular operation | The service, host, or environment that did the work |
| How often do they change? | Different on almost every span | Mostly constant for the life of the process |
| Where are they attached? | To each individual span | Once, to the whole group of telemetry from that source |
| Typical examples | The route requested, the customer plan, the item count | The service name, service version, deployment environment, and host name |
flowchart LR
R["Resource: service name, version, environment"] --> A["Span A with its own attributes"]
R --> B["Span B with its own attributes"]
R --> C["Span C with its own attributes"]
Think of a delivery company. The resource is the delivery van: its registration number, its depot, and its model stay the same all day. The span attributes are the details of each individual parcel the van delivers: the address, the weight, and the delivery time. You would not repeat the van details on every parcel label; you record them once for the van.
Why This Separation Is Smart
Repeating the same information on every span would waste space and bandwidth. By recording unchanging details once as resource attributes, OpenTelemetry keeps each span small. Backends can still combine the two when you search, so you can filter by service name and by route in the same query. Putting a detail in the right place also makes it clearer to readers: if a value never changes during a process’s life, it belongs to the resource.
Ask yourself: does this fact describe the whole service or machine, or just this one operation? Whole service means resource attribute. This one operation means span attribute.
6Semantic Conventions: The Shared Dictionary
Common names for common things make data comparable everywhere.
Imagine ten teams each deciding independently how to record the HTTP method of a request. One writes it as method, another as http_method, another as verb, and another as request-type. Each choice is reasonable, yet no tool can analyze all ten teams’ data together without a long list of special cases. This is exactly the problem that semantic conventions solve.
Semantic conventions are a published, community-maintained set of standard attribute names and meanings for common situations. They cover web requests, databases, messaging systems, remote procedure calls, cloud services, and many other areas. When your instrumentation uses the standard name, every tool that understands the standard can automatically recognize it and provide useful features without custom setup.
Semantic conventions are like a shared dictionary for a team of translators. If everyone agrees that a certain word always means the same thing, documents can be exchanged freely. Without the dictionary, every translation would need an explanation attached.
Some Familiar Examples
| Area | Example attribute key | What it tells you |
|---|---|---|
| Web requests | http.request.method | Which method the request used |
| Web responses | http.response.status_code | The numeric result code that was returned |
| Web routing | http.route | The route pattern that matched, without the variable parts |
| URLs | url.full | The complete web address that was requested |
| Servers | server.address | The name or address of the server being contacted |
| Databases | db.system | Which kind of database was used |
| Messaging | messaging.system | Which messaging technology carried the message |
| Errors | error.type | A short, low-variety description of the kind of failure |
Requirement Levels and Stability
Each convention describes which attributes a given kind of span should always carry, which it should carry when the information is available, and which are purely optional. This helps instrumentation authors decide what to include without guessing. The conventions also carry stability labels. Stable conventions promise not to change in breaking ways, while experimental ones may still be renamed or reshaped. If you build dashboards and alerts on experimental names, plan for occasional updates.
Conventions also describe the span name and the span kind that should accompany the attributes. For example, a span for an incoming web request is expected to use a server kind and a name made from the method and the route pattern, while an outgoing call uses a client kind. The attributes, the kind, and the name work together as one consistent description of the operation.
Names Do Evolve
The conventions are living documents. Over time, the community has refined names to be clearer and more consistent. For example, older instrumentation used names such as http.method and http.status_code for web requests, while newer stable conventions use http.request.method and http.response.status_code. When you read older articles or inspect older data, you may see the earlier names. Many instrumentation libraries offer a transition setting that lets you emit old names, new names, or both for a while, so dashboards and alerts can be migrated gradually. Always check the current published conventions for the version you are using, as some areas are more mature than others.
Renaming an attribute silently breaks every dashboard, alert, and saved search that used the old name. Treat attribute names like a public contract and plan changes with care.
Automatic instrumentation libraries for popular frameworks already add many of the standard attributes for you. You usually only need to add the details specific to your own business.
7Custom Attributes: Adding Your Own Business Details
Standard names cover the technology; custom attributes cover your business.
Semantic conventions describe technical things such as web calls and database queries. They cannot know about your particular business: your customer tiers, your product catalog, your order types, your feature experiments. That is where custom attributes come in. They let you attach your own domain knowledge to spans so that traces can answer business questions as well as technical ones.
Naming Your Own Attributes
Good naming matters even more for custom attributes because no outside standard protects you. Following a few simple habits will keep your data tidy for years.
Use Your Own Namespace
Begin custom keys with a prefix that identifies your company or application, so they can never collide with a future standard name. Never invent keys that begin with the reserved OpenTelemetry prefix.
Use Dots for Levels and Underscores for Words
Group related keys by a common prefix, such as shopping cart details together, and separate words within a level with underscores.
Stay Lowercase and Consistent
Because keys are case sensitive, agree on lowercase and never deviate. One team’s capital letter becomes another team’s missing data.
Describe the Fact, Not the Use
Name the key after what the value is, such as the customer tier, not after what you plan to do with it, such as the alert group. Uses change; facts do not.
Check the Standard First
Before inventing a key, look for an existing semantic convention that already covers the idea. Reusing a standard name gives you free tool support.
Good Business Attributes
Customer Tier
Recording whether a request came from a free, standard, or premium customer lets you check whether your most valuable customers get the experience they pay for.
Cart or Order Size
A numeric count of items often explains slowness. Large carts may trigger slow queries that small carts never reveal.
Experiment or Feature Flag Variant
Noting which variant of a feature a user saw lets you compare performance and error rates between the old and new behaviors during a rollout.
Tenant or Region Identifier
In systems that serve many customers or regions, this makes it easy to see whether a problem is global or limited to one tenant or location.
Keep a short shared document listing your team’s custom attribute names, types, and meanings. It prevents duplicates and helps new engineers instrument consistently.
8When Attributes Are Set, and Why Timing Matters
You can add attributes when a span begins or while it is running, and the difference is important.
A span lives for a period of time, from its start to its end. Attributes can be attached at two moments: at the instant the span is created, or at any later moment before the span ends. After the span ends, it is finished and further changes are ignored.
Span Creation
Details you already know when the work begins, such as the requested route or the target service, can be supplied right at the start.
During the Span
Details that become known along the way, such as the number of rows returned or the result of a cache lookup, can be added as the work progresses.
Span End
Once the span ends, it is sealed. Attributes added after this point are ignored, so make sure everything important is recorded before the work finishes.
Why Creation-Time Attributes Are Special
There is a subtle reason to supply important details at creation. When tracing is configured to keep only a portion of all traces, the decision about whether to record a span is often made at the very moment the span starts. At that moment, the only attributes the decision logic can see are the ones supplied at creation. If a detail that should influence the decision, such as the customer tier or the type of operation, is only added later, the decision logic cannot use it.
Think of a security guard who decides at the door whether to inspect a visitor’s bag. The guard can only use what is visible at the door: the visitor’s badge, uniform, and appointment. Information that the visitor will reveal later inside the building cannot help the guard make the choice at the door.
Manual and Automatic Instrumentation Working Together
In most real applications, attributes come from two sources at once. Automatic instrumentation libraries wrap popular frameworks, web servers, database drivers, and messaging clients, and they create spans and attach the standard attributes without you writing any tracing code. Manual instrumentation is the code you add yourself to enrich those spans or create new ones around your own business logic.
A healthy approach is to let automation do the broad, repetitive work and use manual attributes sparingly for the details that only you know. A common technique is to find the span that is currently active when your business code runs and add your custom attributes to it, rather than creating many new spans just to hold a few labels. This keeps traces compact and easy to read.
Before creating a new span just to carry some details, check whether the details could simply be added as attributes on the span that already exists. Fewer, richer spans are usually easier to understand than many tiny ones.
Overwriting and Duplicates
If you set the same key more than once on a single span, the last value written wins. This can be useful, for example when updating a status field as work progresses. But it can also hide mistakes when two pieces of code accidentally use the same key for different meanings. Choose specific, descriptive keys so unrelated code never collides.
Adding important attributes at the very end of a long operation, after an error has already caused the code to exit early. Make sure key attributes are recorded before any step that might fail.
9Attributes, Events, Links, Status, and Baggage: Choosing the Right Tool
Several features carry extra information; picking the right one avoids confusion.
Attributes are not the only way to add information to a trace. OpenTelemetry offers several related features, and beginners often wonder which one to use. Each has a distinct purpose, and using the right one makes your traces clearer and cheaper to store.
Attributes
Describe the span as a whole: facts that are true about the operation from beginning to end.
Events
Record something that happened at a specific moment inside the span, such as an exception or a retry.
Links
Point to other related spans that are not the parent, such as the original requests behind a batch job.
Status
Summarize the outcome of the span as unset, successful, or failed, in a form every tool understands.
Baggage
Carry key-value information along with a request from service to service so other services can read it.
| If you want to record… | Use | Reason |
|---|---|---|
| The route or customer tier of an operation | Attribute | It is a fact about the whole span |
| An exception that occurred partway through | Event | It happened at a specific moment |
| The batch job’s relationship to many source requests | Links | There are many related spans, not one parent |
| Whether the operation succeeded | Status | Every tool understands status uniformly |
| A user identifier that downstream services must know | Baggage | It must travel across service boundaries |
An Important Point About Baggage
Baggage is often misunderstood. It travels with the request across service boundaries, but it is not automatically copied onto spans. If you want a baggage value to appear as a span attribute so you can search by it, you must deliberately copy it, usually with a small piece of configuration or code that reads the baggage and sets matching attributes. Also remember that baggage is sent in request headers to every service the request touches, including external ones, so it must never contain secrets.
flowchart LR
A["Span"] --> B["Attributes: facts about the whole span"]
A --> C["Events: moments inside the span"]
A --> D["Links: related spans elsewhere"]
A --> E["Status: success or failure"]
Do not record failure only as a custom attribute. Use the span status for the outcome so that every tool can show errors consistently, and add attributes for extra detail such as the kind of error.
10The Journey of an Attribute from Application to Dashboard
Following one attribute end to end shows every place it can be changed or lost.
An attribute is created inside your application, but it is eventually read by a person looking at a screen. Between those two points it passes through several stages. Knowing the stages helps you troubleshoot the common problem of “I set this attribute, but I cannot find it”.
sequenceDiagram
participant App as Application code
participant SDK as OpenTelemetry library
participant Col as Collector
participant Back as Tracing backend
participant User as Engineer
App->>SDK: Set an attribute on a span
SDK->>SDK: Apply limits and finish span
SDK->>Col: Export the span in batches
Col->>Col: Receive, process, export
Col->>Back: Deliver the span
User->>Back: Search or filter by attribute
Stage 1: Your Code or Auto-Instrumentation
The attribute begins life in code you wrote or in an instrumentation library that did the work for you. Auto-instrumentation adds many standard attributes by itself. Your own code adds the business-specific ones.
Stage 2: The OpenTelemetry Library
The library inside your application receives the attribute and stores it on the span. It also enforces limits, such as the maximum number of attributes per span and, if configured, the maximum length of values. Extra attributes beyond the limit are dropped, and the span records how many were dropped.
Stage 3: Export
When a span ends, it is placed in a buffer and sent out in batches, usually to a Collector. Some samplers decide at this stage or earlier whether the span is kept at all, which is why a missing span means missing attributes.
Stage 4: The Collector
The Collector receives the span and may run processors on it. These can add, change, hide, or remove attributes, and can use them to route or sample spans. The next chapter looks at this in detail.
A Note on Arrays and Large Values
Array attributes are useful for lists, such as the categories of products in a basket, but they are harder to search in some backends than single values. If you often need to filter on one item from the list, consider whether a separate attribute would serve better. Very large text values, such as long error messages, can also be costly to store and slow to display. Keep values short and meaningful, and let events carry larger descriptive text where appropriate.
Stage 5: The Backend
Finally, the backend stores the span and lets people search it. Some backends index every attribute, while others index only chosen ones to save cost, and some limit how many unique attribute keys are searchable. An attribute can exist in storage yet be awkward to query if it is not indexed.
If an attribute seems missing, check the stages in order: was it set before the span ended, did a limit drop it, did a processor remove it, and does the backend index it?
11Working with Attributes Inside the Collector
The Collector is the central workshop where attributes can be cleaned, enriched, and used for decisions.
The OpenTelemetry Collector is a standalone program that sits between your applications and your tracing backend. Its processors can inspect and modify spans in flight, and attributes are the main thing they work with. This is powerful because you can fix or improve attributes centrally, without redeploying every application.
Add or Enrich
Insert missing attributes, such as an environment label, so every span carries consistent context.
Rename or Update
Correct inconsistent key names or normalize values, which helps while migrating between naming versions.
Hide or Hash
Remove sensitive attributes or replace values with irreversible fingerprints before data leaves your network.
Delete Noise
Drop attributes nobody uses, reducing storage cost and clutter.
Filter
Discard whole spans, such as health checks, based on their attributes.
Sample by Attribute
Keep all spans with errors or slow responses and only a fraction of the routine ones.
The Processors Behind These Tasks
Several processors specialize in attributes. An attributes processor offers straightforward actions such as inserting, updating, deleting, and hashing attributes. A more flexible transform processor uses a small expression language to make richer changes based on conditions. A redaction processor focuses on hiding sensitive values. A filter processor drops data that matches certain conditions, and tail-based sampling processors can decide to keep or drop a whole trace based on the attributes of its spans, once the whole trace has been seen.
The Collector is like a mailroom. Before parcels go out, staff can add missing labels, correct wrong ones, cover sensitive details with tape, throw away junk mail, and pick out urgent parcels for faster handling. The senders do not need to know any of this is happening.
Head Sampling versus Tail Sampling
Head sampling makes the keep-or-drop decision when a trace begins, so it can use only the attributes known at that moment. Tail sampling waits until a trace is complete and then decides, so it can use attributes recorded anywhere in the trace, such as an error status or a long total duration. Tail sampling gives smarter results but needs more memory and coordination in the Collector, because all the spans of a trace must be held together until the decision.
Attributes you record well are the raw material for sampling rules. A rule like “always keep traces for premium customers” is only possible if the customer tier is recorded as an attribute.
12Using Attributes to Find and Fix Problems
Attributes turn a pile of traces into answers.
The ultimate purpose of attributes is to help people solve problems quickly. Observability tools generally let you do three things with them: filter, group, and compare. Together these let you move from a vague complaint to a precise cause in a few steps.
Start with the Symptom
Find the slow or failing spans, using duration or status. This tells you where to look.
Group by Attributes
Break the bad spans down by region, version, customer tier, or route. A pattern often jumps out, such as one region accounting for nearly all the slowness.
Compare Good against Bad
Look at attribute values in healthy spans versus unhealthy ones. The attribute that differs most is your strongest clue.
Confirm with a Narrow Filter
Filter on the suspected attribute combination and check whether the problem disappears when you exclude it.
A Slow Checkout Mystery
Customers complain that checkout is sometimes slow. The team filters checkout spans by duration and groups by cart item count. They discover that slow spans almost always involve carts with more than fifty items, because a particular database query scales badly. Without the item-count attribute, the pattern would have been invisible.
A Rollout Gone Wrong
After a new release, error rates climb slightly. Grouping by the service version attribute shows that all the errors come from the new version, even though only a fraction of traffic uses it. The team rolls back that version within minutes.
Attributes Beyond Troubleshooting
Attributes are not only for emergencies. Product teams use them to understand how real people use a system, such as which features are most used or which device types are slowest. Capacity planners use them to see which tenants or workloads consume the most resources. Security teams use them to spot unusual patterns, such as a sudden burst of failed logins from one network. Finance teams sometimes use them to attribute infrastructure costs to the teams or products that cause them. A well-chosen attribute set therefore serves many audiences at once, which is a strong reason to design it carefully and share it widely.
Because so many people may depend on the same attributes, it pays to treat the most important ones as a small shared contract. Announce changes, give old names a transition period, and keep a clear owner for each important attribute. This turns attributes from a private debugging aid into dependable organizational data.
When deciding what to record, imagine the questions you will ask during an outage. Each question that begins with “is it only…” suggests an attribute worth capturing.
13Limits, Cardinality, and Cost
More attributes are not always better; every label has a price.
Built-In Limits
To protect applications from runaway memory use, OpenTelemetry libraries enforce limits on spans. By default, a span can hold up to one hundred twenty-eight attributes. The libraries can also be configured with a maximum length for text values, truncating anything longer. When limits are exceeded, extra attributes are dropped, and the span keeps a count of how many were dropped so the loss is visible rather than silent. These limits can be adjusted through settings, often environment variables, but raising them has memory costs.
Understanding Cardinality
Cardinality means the number of different values an attribute can take. A region attribute might have a dozen values, which is low cardinality. A user identifier might have millions, which is high cardinality. A request identifier is unique every time, which is the extreme case.
High-cardinality attributes are less dangerous on spans than on metrics, because spans are stored individually rather than combined into time series. In fact, high-cardinality values like a request identifier are often exactly what you need to find one specific trace. Still, they can raise indexing costs in some backends, and they are poor choices for the span name. The span name should stay low in cardinality, with variable details moved into attributes.
Think of the index at the back of a book. An index entry for a topic that appears on a few pages is useful. An index entry for every single word, repeated everywhere, would make the index as big as the book and not helpful. Backends that index every unique attribute value can become costly in a similar way.
Span Names versus Attributes
A common beginner error is placing variable data inside the span name, for example including a specific user number or full web address in the name. This creates thousands of different span names that cannot be grouped. The better practice is a general name describing the kind of operation, such as the method and route pattern, with the specific details stored as attributes.
Putting identifiers inside span names. You lose the ability to group similar operations, and backends that group by name will show thousands of near-duplicate entries.
14Security and Privacy of Span Attributes
Attributes are written by developers and read by many people, so treat them as data that can leak.
Attributes can easily contain sensitive information by accident. A developer adds the full web address to help debugging, and the address happens to contain a password reset token. Another records a database statement, and the statement contains a customer’s email address. Because traces are shared widely and stored for a long time, such leaks can spread far and last long. Handling attributes responsibly is therefore both a security and a legal matter.
What to Keep Out of Attributes
Secrets
Passwords, access tokens, API keys, and session identifiers must never appear.
Payment Details
Card numbers and bank details are heavily regulated and have no place in traces.
Personal Data
Names, email addresses, phone numbers, and precise locations may be regulated; prefer opaque identifiers.
Raw Payloads
Whole request bodies and query statements with real values often contain hidden sensitive content.
Defense in Depth
The best defense is layered. First, design instrumentation so that sensitive values are never recorded. Second, review the attributes that auto-instrumentation adds by default, since some captures can include more than you expect, such as full web addresses with query strings. Third, use the Collector as a safety net: redaction, hashing, and deletion rules there can remove sensitive attributes even if a developer makes a mistake. Fourth, restrict who can view traces in the backend and how long data is kept.
Removing a sensitive value from a trace after it was already stored is much harder than preventing it from being recorded. Prevention at the source and a Collector safety net together offer the best protection.
15Real-World Examples
Seeing attributes in familiar situations makes the ideas concrete.
An Online Shop
A web request span carries the standard method, route, and status code attributes automatically. The team adds the cart item count, the customer tier, and the payment method type. During a sale, they quickly learn that one payment method is slower than the others, and they take it to the provider with evidence.
A Database Call
A database span carries the type of database, the name of the database, and the operation being performed, following the standard conventions. A dashboard grouped by operation type shows that a particular kind of query is responsible for most of the time spent in the data layer.
A Message Queue
A producer span and a consumer span carry the messaging system, the destination name, and the operation type. By following these attributes, engineers can see which queue is backing up and which consumers are slow to handle messages.
A Multi-Tenant Software Service
A service used by many business customers records a tenant identifier on every span. When one customer reports slowness, support filters traces by that tenant and shows the engineers exactly what that customer experienced, without wading through everyone else’s data.
A Gradual Feature Rollout
A team releases a new recommendation algorithm to ten percent of users. Each relevant span carries the algorithm variant. After a day, comparing the duration and error rate between variants shows the new algorithm is faster but occasionally fails, so the team fixes it before widening the rollout.
A Mobile Application Backend
The backend records the application version and the operating system family sent by the mobile client. When crashes spike, grouping by application version reveals a single faulty release, allowing a targeted fix instead of a long search.
16Advantages and Trade-offs
Attributes are one of the highest-value features in tracing, but they require discipline.
Advantages
- They turn timing data into explanations by adding context.
- They let you filter, group, and compare spans to find patterns.
- Standard names make data portable across tools and teams.
- Custom attributes connect technical traces to business questions.
- They feed smart sampling and routing decisions in the Collector.
- The key-value model is simple to learn and flexible to use.
Disadvantages / Trade-offs
- Too many or very large attributes increase memory, network, and storage cost.
- Inconsistent naming makes data hard to combine and search.
- Sensitive data can leak into traces by accident.
- Renaming attributes later breaks dashboards and alerts.
- Only a few simple value types are supported, so complex data must be flattened.
A Simple Starting Recipe
If you are unsure where to begin, try a small recipe. First, make sure your services report their name, version, and environment as resource attributes. Second, enable automatic instrumentation so that web, database, and messaging spans carry the standard attributes. Third, pick the three or four business facts your team most often asks about during incidents, such as customer tier, region, and feature variant, and record them on the relevant spans. Fourth, write the names and meanings down in one shared page. This modest beginning already delivers most of the value, and you can expand it gradually as new questions appear.
Balancing the Two Sides
The goal is not the maximum number of attributes but the most useful ones. Start with the standard attributes provided by instrumentation, add a small set of business attributes that answer your most common questions, and grow thoughtfully from there. Review your attributes periodically and remove ones that nobody queries. A small, consistent, well-understood set beats a huge, messy one.
Before adding an attribute, ask who will use it and for what question. If nobody can answer, the attribute probably adds cost without value.
17Best Practices and Common Mistakes
A handful of habits prevent most problems.
Habits Worth Building
Reuse Standard Names
Check the semantic conventions first, so tools can understand your data automatically.
Namespace Custom Keys
Use your own prefix and consistent lowercase naming to avoid clashes.
Use Proper Types
Keep numbers numeric and flags as true-or-false so they can be calculated and filtered.
Set Key Details Early
Supply details that influence sampling when the span is created.
Protect Sensitive Data
Never record secrets, and add Collector redaction as a safety net.
Document Your Attributes
Keep a shared list of names, types, and meanings for your team.
Mistakes to Avoid
Problem
Developers record whole request bodies, full database statements with real values, or complete web addresses with query strings as attributes to make debugging easier.
Why It’s Harmful
These values often contain personal data, tokens, or secrets. They also bloat spans and increase storage cost, and they may violate privacy regulations.
Correct Approach
Record only the specific, safe fields you actually need, prefer opaque identifiers over personal details, and configure the Collector to redact or remove sensitive values as a second line of defense.
Problem
Each team invents its own names for the same idea, such as several different spellings for the customer plan, with mixed capitalization.
Why It’s Harmful
Searches miss data, dashboards show partial results, and combining data across services requires endless special cases.
Correct Approach
Agree on a shared naming guide, reuse semantic conventions where they exist, and review new attribute names before they spread across services.
Problem
Variable information such as user numbers or full web addresses is placed in the span name instead of in attributes.
Why It’s Harmful
It creates thousands of unique span names, making it impossible to group similar operations and overwhelming backends that rely on names.
Correct Approach
Keep span names general and low in variety, such as a method plus a route pattern, and move the specific details into attributes.
Treating attributes as a place to dump everything “just in case”. Unused attributes still cost money and attention. Be selective and intentional.
18Frequently Asked Questions
Quick answers to the questions beginners ask most often.
The idea is the same: a name paired with a value. Other tracing systems used words like tag or label for it. In OpenTelemetry, the standard term is attribute, and it follows a specific set of rules about names and value types.
By default, most OpenTelemetry libraries allow up to one hundred twenty-eight attributes per span, though this can be configured. Attributes beyond the limit are dropped, and the span records the number dropped.
Text, true-or-false values, whole numbers, decimal numbers, and arrays of a single one of those types. Complex nested objects are not supported, so flatten them into several attributes.
The most recent value replaces the earlier one. A span holds only one value per key.
No. After the span ends it is finished, and further changes are ignored. Record everything important before the work completes.
A span attribute describes one operation and usually differs from span to span. A resource attribute describes the service, host, or environment producing the telemetry and stays the same across all its spans.
Use an attribute for a fact about the whole operation. Use an event for something that happened at a specific moment during it, such as an exception or a retry.
Usually not. Automatic instrumentation for popular frameworks adds most of them for you. You mainly add the custom details that are specific to your business.
Opaque identifiers are usually acceptable and very useful, but personal details such as names, emails, or phone numbers may be regulated. Follow your organization’s privacy rules, and use the Collector to redact where needed.
Common reasons are that it was set after the span ended, it exceeded a limit and was dropped, a Collector processor removed it, the span was not sampled, or the backend does not index that attribute. Check each stage of the journey in order.
19Summary and Key Takeaways
A span attribute is a key-value label attached to a span that describes the particular operation it represents. While a span’s built-in parts record when the work happened and whether it succeeded, attributes record the open-ended context that makes a trace explainable: the route, the customer tier, the item count, the software version. Used well, with standard names, sensible types, careful timing, and strong privacy habits, attributes turn traces from simple timelines into powerful tools for finding and fixing real problems. Used carelessly, they raise costs and risk leaks. Start small, stay consistent, and let your real questions guide what you record.
Key Takeaways
- Attributes are key-value labels — they describe one specific operation, adding context that timing and status alone cannot provide.
- Types are simple and intentional — text, true-or-false, whole numbers, decimals, and arrays of one type; keep numbers numeric and flatten nested data.
- Span versus resource — span attributes describe one operation, while resource attributes describe the service or host and are recorded once for all its spans.
- Semantic conventions are the shared dictionary — reuse standard names so tools understand your data, and namespace your own custom keys.
- Timing matters — attributes can be set at creation or while the span runs, but not after it ends; details that influence sampling should be supplied at creation.
- Choose the right feature — use attributes for facts about the whole span, events for moments inside it, links for related spans, status for outcome, and baggage for cross-service context.
- Mind cost and privacy — respect limits, keep span names low in variety, never record secrets, and use the Collector as a safety net for redaction and cleanup.