Before we meet the tool, let us feel the problem it solves.

Every program that is watched by OpenTelemetry produces telemetry, which is the general word for the three kinds of signals software can send about itself: traces, which follow one request across services; metrics, which are numbers measured over time; and logs, which are lines of text describing events. Each signal carries attributes, which are small named labels attached to the data. A span for a web request might carry the labels “http method equals GET”, “route equals checkout”, and “status code equals 200”. Labels are what let you slice a chart by route or search for all errors from one region.

The trouble is that labels are written by people and libraries, not by one careful editor. Imagine a company with fifty services written by ten teams. One team calls a label “customer id”. Another calls it “customerId”. A third forgets to add it at all. An old library still uses an outdated name for the HTTP method, while a new one uses the current name. A developer, in a hurry to debug something, adds a label containing a user’s email address and forgets to remove it. Another puts a full web address with a secret token in the query string into a label. A metric is labeled with a request ID that is different every time, creating millions of unique lines on a chart and a very large bill.

You could ask every team to fix their own code. Sometimes that is the right answer. But it takes months, new code keeps arriving, third-party libraries are out of your control, and urgent problems such as a privacy leak cannot wait. What you want is one central place, under the control of a platform or operations team, where labels can be corrected for everyone at once. That place is the Collector, and the tool inside it built for editing labels is the Attributes Processor.

A short glossary makes everything after this easier to read.

Three more ideas deserve a moment. First, resource attributes describe the thing that produced the telemetry, such as the service name, its version, and the machine it runs on. They are shared by everything that service sends. They are different from the attributes on an individual span, log record, or data point, which describe one single event. This difference will matter greatly later, because the Attributes Processor edits the second kind, not the first.

Second, a regular expression, often called a regex, is a compact pattern language for matching text. For example, a pattern can say “any text that starts with the word user followed by digits”. Some actions in the Attributes Processor use regular expressions to find or cut text. They are powerful but can be slow if written carelessly. Third, hashing means turning a value into a scrambled code of fixed length using a one-way mathematical recipe. Two equal inputs always give the same code, but you cannot run the recipe backward to recover the original.

A clear definition, a clear list of what it can do, and a clear list of what it cannot.

The Attributes Processor is a Collector component that modifies the attributes of telemetry as it passes through a pipeline. It works on three signals: the attributes of spans in a trace pipeline, the attributes of log records in a log pipeline, and the attributes of data points in a metric pipeline. You describe what you want in a list of actions, and the processor applies them, one after another, to every item that is selected for editing.

The processor offers a small and memorable set of actions. You can insert an attribute that is missing, update one that already exists, or upsert, which means insert or update, whichever applies. You can delete an attribute. You can hash its value into a scrambled code. You can extract pieces of its value into new attributes using a pattern. And you can convert its value from one type to another. We will study each in its own chapter.

It is just as important to know what the processor does not do. It does not edit resource attributes, which describe the producing service. For that, the Collector offers the Resource Processor. It does not drop whole spans or logs; for that there is the Filter Processor. It does not rewrite the body of a log, the name of a span, or the value of a metric. It does not combine many data points into one. And it does not decide which traces to keep; that belongs to sampling processors. The Attributes Processor is a narrow, sharp tool, and its narrowness is a strength: because it does one job, its behavior is easy to predict and its configuration is easy to read.

A Short History of Why It Exists

In the early days of tracing and monitoring, each vendor shipped its own agent, and each agent came with its own tricks for tweaking labels. When teams moved to OpenTelemetry to avoid being locked to one vendor, they needed a neutral place to do the same tweaks. The Collector became that place, and the Attributes Processor was one of its earliest and most widely used processors. It grew out of simple, repeated needs: add a label, remove a label, hide a label. Over time, the community added hashing, extraction, and conversion, and more powerful general-purpose processors appeared beside it. Today it remains the friendly, first-choice tool for the common cases.

How It Looks to the User

You do not write a program to use it. You write a short description in the Collector’s configuration file. That description names the processor, optionally says which items to select, and lists the actions in order. Each action states a label key, an action type, and, where needed, a value or source. The Collector reads this description when it starts, builds the processor, and applies it to the pipeline. Changing the rules means changing the description and restarting or reloading the Collector. Because the description is plain text, it fits naturally into version control, code review, and automated deployment.

Why Edit Labels in the Collector?

There are four main reasons to do this work in the Collector instead of inside each application. The first is speed of change. A single edit to a Collector configuration takes effect for every service sending data through it, often within minutes, without waiting for ten teams to ship new code. The second is consistency. One rule guarantees that every service uses the same name for a label. The third is control. Platform and security teams, not application developers, own the Collector, so they can enforce company rules on data leaving the company’s network. The fourth is flexibility with vendors. If you send data to several monitoring products, each may want labels in a slightly different shape, and the Collector can adapt them on the way to each destination.

The Honest Trade-off

Editing in the Collector is not always the best place. Data has already left the application, crossed the network, and been received by the Collector before the edit happens. For truly secret data, removing it at the source is safer, because it never travels at all. The Collector approach is best seen as a strong safety net and a convenient control point, rather than the only line of defense. We will return to this in the security chapter.

The processor is one stop on a path. Seeing the whole path makes its role clear.

The Collector is built from three kinds of parts. Receivers are the front doors. They accept data in various formats and protocols, such as the standard OpenTelemetry protocol, and turn it into the Collector’s internal form. Processors are the workstations in the middle. They inspect and change the data. Exporters are the delivery docks. They send the finished data to a monitoring product, a storage system, or another Collector. A pipeline connects chosen receivers, processors, and exporters for one signal type, and the data flows through the processors in the exact order they are listed.

flowchart LR
  A["Applications and SDKs"] --> B["Receiver"]
  B --> C["Memory Limiter Processor"]
  C --> D["Attributes Processor"]
  D --> E["Other Processors such as Filter or Sampling"]
  E --> F["Batch Processor"]
  F --> G["Exporter to Monitoring Backend"]
  F --> H["Exporter to Long-Term Storage"]
    

Let us walk through the figure from left to right. Applications send data to a receiver. The memory limiter processor comes first by convention, because its job is to protect the Collector from running out of memory by refusing data when the Collector is overloaded. Then comes the Attributes Processor, which edits labels. After it may come other processors, such as filters that drop unwanted items or samplers that keep only some traces. The batch processor usually comes last. It gathers many items into bigger groups so that exporting is efficient. Finally, exporters deliver the data to one or more destinations.

Why Order Matters

The order of processors is not a matter of taste. Each processor sees the result of the one before it. If a sampling decision depends on a label, the label must exist before sampling runs. If you hash or delete a secret label, you want that to happen before any exporter sees the data, and before any later processor that might copy the label somewhere else. If a filter drops data based on a label that the Attributes Processor renames, the filter must come after the rename, using the new name. Planning the order is like planning a recipe: you must wash the vegetables before you chop them.

Agents and Gateways

The Collector can run in two common shapes. An agent runs next to each application, for example on the same machine or as a helper beside each group of containers. A gateway is a central Collector, or a group of them, that many agents send data to. You can run the Attributes Processor in either. Running it in an agent means data is cleaned very close to its source, before it travels across the network. Running it in a gateway means one team controls the rules in one place. Many companies do both: agents add local facts and remove obviously unsafe labels, while gateways enforce company-wide naming and privacy rules.

Pipelines Per Signal

Traces, metrics, and logs flow through separate pipelines in the Collector. A single Attributes Processor definition can be listed in several pipelines at once, and it will edit each signal according to the same rules, using the parts of the rules that make sense for that signal. A rule that matches on a span name will only affect trace pipelines, while a rule that matches on a metric name will only affect metric pipelines. When your needs differ between signals, it is cleaner to define one named instance per signal, so that each pipeline has rules fitted to it.

What Happens When Data Passes Through

When the Collector hands a batch to the processor, the batch is a bundle of resources, each holding scopes, each holding many spans, logs, or data points. The processor walks through the items inside the bundle and edits their labels in place. The shape of the bundle is left alone. This is why resource-level facts are untouched, and why the processor is so cheap in structure: it never needs to rebuild the bundle or copy large amounts of data.

Named Instances

You can define several copies of the same processor, each with its own settings, by giving each one a short name after the processor’s type. For example, one instance might be named for redaction and another for adding team labels. Each instance can then be placed in the pipelines where it is needed. This lets you keep small, clearly named rule sets instead of one giant list of actions, which makes the configuration easier to review.

Seven actions cover almost every label edit you will ever need.

Insert

The insert action adds a label only when the label is not already there. If it is there, the existing value is left alone. This makes insert the polite action. It fills gaps without overriding what applications deliberately said. A typical use is adding a default value, such as a team name or a cost center, for services that did not set one themselves.

Update

The update action changes a label’s value only when the label already exists. If the label is missing, nothing happens. It is useful for correcting values, such as replacing an old service nickname with its official name, without accidentally creating labels on data that never had them.

Upsert

The word upsert is a blend of update and insert. It sets the label to the given value whether or not the label already existed. Use it when you want to be certain of the final value, such as forcing a normalized region name on all data. Because it overrides what applications said, use it with some care. If an application set a label for a good reason, an upsert will erase that reason.

Delete

The delete action removes a label completely. It is the main tool for removing sensitive information and for cutting down on high-cardinality labels. Cardinality means the number of different values a label can take. A label that holds a different value on every request, such as a request ID, has very high cardinality, and when attached to a metric it creates a separate line on the chart for every request, which can overwhelm storage and raise costs. Deleting such labels from metric data points keeps the data useful and affordable.

Hash

The hash action replaces a label’s value with a scrambled code produced by a one-way recipe. The advantage over delete is that equal inputs give equal codes, so you can still count how many distinct users appeared, or follow one user’s activity, without ever seeing who they are. Different versions of the processor have used different hashing recipes, and newer ones have been moving to stronger recipes, so check the documentation for your version.

A word of caution is needed here. Hashing is not a perfect privacy shield for values that are easy to guess. If the value is an email address or a phone number, an attacker who knows the recipe can try millions of likely values and compare the codes. Hashing is best for values that are long, random, and hard to guess, and for cases where you want to avoid showing raw values to casual viewers. For truly sensitive data, deleting is safer.

Extract

The extract action uses a regular expression with named parts to cut a label’s value into pieces and store each piece as its own new label. Suppose a label holds a long web address such as a path with an order number inside. A pattern can pull the order number out into its own label, so you can search or group by it. The original label stays in place unless you delete it separately. Extract only works if the source label exists and the pattern actually matches; otherwise it quietly does nothing.

Convert

The convert action changes the type of a label’s value. Labels may hold text, whole numbers, decimal numbers, or true and false. Sometimes data arrives with the wrong type: a status code stored as text, or a count stored as a decimal. Different backends sort, compare, and aggregate by type, so a number stored as text can behave strangely in charts. Convert fixes this. If a value cannot be sensibly converted, such as turning the word “banana” into a number, the value is typically left as it was.

Choosing the Right Action: A Quick Guide

When you face a new label and are not sure which action to pick, ask a few questions in order. Do you want the label gone? Then delete. Do you want to keep it but hide its value? Then hash, remembering the limits of hashing. Do you want to fill a gap without overriding anything? Then insert. Do you want to correct values that exist but leave gaps alone? Then update. Do you want the value to be certain no matter what was there? Then upsert. Is one label carrying several facts? Then extract. Is a value of the wrong type? Then convert. Most real tasks need only one or two of these, and thinking through the questions in this order prevents the common mistake of using upsert for everything.

A Note on Value Types

Every label value has a type: text, whole number, decimal number, true or false, or in some cases a list or a map. The type matters because backends treat them differently. A text value of “200” and a number value of 200 may be stored, indexed, and searched in different ways. When you add a label with a fixed value, think about the type you want. When you copy a value from another label, the type is carried along. When you extract pieces with a pattern, the pieces start as text, and you may want a convert action afterward to turn numeric pieces into real numbers. A little attention to types saves surprises in dashboards and alert rules later.

Names, Cases, and Exactness

Label keys are matched exactly, including capital letters and punctuation. A rule aimed at a label called “customer.id” will not touch “customer_id” or “Customer.ID”. This precision is useful, since it prevents accidental changes, but it also means that a small typo makes a rule silently do nothing. Always copy label names from real data, such as a debug output, rather than typing them from memory.

Rename: Two Actions Working Together

There is no single rename action, but you can build one from two. First, insert a new label whose value is copied from the old label. Then delete the old label. The two actions run in order, so the value moves to the new name. This pattern is common when an old library uses a retired name and your dashboards use the new name. It is also a good example of why the order of actions matters.

Every action needs a value to work with. There are three places it can come from.

When you write an action that adds or changes a label, you tell the processor where the new value comes from. There are three choices. The first is a fixed value that you type into the configuration. This is the simplest: for example, every item gets the same team name. The second is another attribute on the same item, by naming it as the source. The processor copies the value from that label. This is how renaming and copying work. The third is the context, which means information about the incoming request that is not part of the telemetry itself, such as a header or piece of metadata that the receiver captured.

A Closer Look at the Context

Telemetry arrives at a receiver through a network request, and that request may carry extra information, such as the name of the customer who sent it, in its headers. By default, receivers do not keep this information. If you ask a receiver to include request metadata, the information becomes available in the context, and the Attributes Processor can copy a chosen piece onto each span, log, or data point as a label. This is a very useful trick for multi-tenant setups, where one Collector serves many customers and every item must be tagged with the customer it belongs to, in a way the customers’ own applications cannot fake.

Without any selection rules, the processor edits everything that flows through it. Selection rules narrow it down.

By default, the Attributes Processor applies its actions to every span, log record, or data point that reaches it. That is often too broad. You may want to hide labels only for one service, or add a team label only for one group of routes. For this, the processor offers two optional rule groups. An include block says “edit only items that match this description”. An exclude block says “do not edit items that match this description”. If both are present, the processor first checks the include rules and then removes from that set anything matching the exclude rules.

flowchart TD
  S["Telemetry item arrives"] --> Q1{"Does it match the include rules, if any?"}
  Q1 -->|"No"| P["Pass through untouched"]
  Q1 -->|"Yes or no include rules"| Q2{"Does it match the exclude rules, if any?"}
  Q2 -->|"Yes"| P
  Q2 -->|"No"| A1["Run action 1"]
  A1 --> A2["Run action 2"]
  A2 --> A3["Run the remaining actions in order"]
  A3 --> O["Send to the next processor"]
  P --> O
    

Look at the figure carefully. An item that is not selected is not dropped. It simply passes through unchanged, and goes on to the next processor. This is an important difference from a filter, which removes items entirely. The Attributes Processor never removes whole items; it only chooses whether to edit them.

What You Can Match On

The descriptions you can match against depend on the signal. For spans, you can match on the service name, the span name, the kind of span, such as server or client, and on attributes, among other things. For logs, you can match on log body text, severity, and attributes. For metrics, you can match on metric names and attributes. Across all signals, you can match on resource attributes and on the name of the instrumentation library that produced the data. Each match can use one of two styles. A strict match means exact equality. A regular expression match means a pattern. Strict matching is faster and easier to read, so prefer it when an exact name will do.

Include and Exclude Together

Using both blocks at once gives you fine control. Imagine a rule that should edit all spans from the checkout services, except those for the health check route. The include block names the checkout services, and the exclude block names the health check route. The processor first narrows to the checkout services, then removes health checks from that group. This reads naturally to a human reviewer, and it keeps the rule honest, because the exception is written next to the rule instead of hidden in someone’s memory.

Matching on Attributes

A common pattern is to select items that carry a particular label. For example, “edit only spans where the database system label equals a certain value”. Matching on a label’s presence or value lets you apply sensitive rules only where sensitive data is likely to appear, which reduces the risk of accidentally changing unrelated data and also saves processing time.

Following a single span, log, or data point through the processor shows exactly how the rules behave.

When a batch of telemetry reaches the Attributes Processor, the processor walks through it item by item. For each item, it first applies the selection rules. If the item is not selected, it moves on. If it is selected, the processor runs through the list of actions in the order you wrote them. Each action sees the result of the one before. This is the single most important behavior to remember: actions run in sequence, and later actions can depend on earlier ones.

flowchart TD
  K["An action targets one label key"] --> E{"Does the key already exist on the item?"}
  E -->|"No"| N["insert adds it. update does nothing. upsert adds it. delete does nothing."]
  E -->|"Yes"| Y["insert does nothing. update replaces it. upsert replaces it. delete removes it."]
    

A Mental Model: The Assembly Line

A helpful way to hold all of this in your mind is to imagine an assembly line with a row of workers. Each worker has one small instruction card. The first worker looks at an item, checks whether it is one they should handle, and if so performs the instruction on the card. The item then moves to the next worker, who does the same. At the end, the item rolls off the line, changed in exactly the ways the cards say, in exactly the order the workers stand. Nobody on the line remembers earlier items, and nobody looks ahead at later ones. This is why the processor is so predictable: for a given item and a given list of cards, the result is always the same.

Why Sequence Matters

Consider the rename pattern. The first action copies the value from the old label into a new label. The second action deletes the old label. If you wrote them in the opposite order, the delete would run first, and the copy would find nothing to copy, leaving you with neither label. Likewise, if you hash a label and then try to extract from it, the extract would see the scrambled code instead of the original text. When you plan actions, imagine a human following the list from top to bottom with a pencil, and ask what each step sees.

Work Done in Memory

The processor works on the data directly in memory. It does not write anything to disk and does not call outside services. Each action is a small operation on a map of keys and values: look up a key, add a key, replace a value, or remove a key. This is quick. The more expensive operations are those that involve regular expressions, since pattern matching costs more than simple lookups, and hashing, which does real arithmetic on every value.

Metrics Need Extra Thought

Metric data points are a little different from spans and logs. A metric is made of many data points, each with its own set of attributes, and those attributes act like the identity of one line on a chart. Two data points with the same metric name and the same set of attributes are treated as the same line. If you delete a label from data points, two lines that used to be separate may now have identical identities. A backend that receives two data points claiming to be the same line at the same time may keep only one, merge them in an unexpected way, or reject them. When you remove labels from metrics, make sure the remaining labels still distinguish the lines you care about, or follow the removal with a step that properly combines data points, using a processor made for aggregation.

Let us follow one imaginary span from an application to a dashboard and watch its labels change.

Suppose a web service in a company sends a span describing a checkout request. As it leaves the application, the span carries these labels: a route, an HTTP method under an older name, a full web address including a secret token in the query string, and a user email. The platform team has configured a gateway Collector with an Attributes Processor to fix these things. The rules run in the following order.

Notice what stayed the same. The span’s name, timing, parent, and status were untouched. The application did not change a line of code. The edits were applied centrally, by rules that a small team can read and review. If tomorrow the company decides to start hashing another label, the platform team adds one line to the configuration, reloads the Collector, and the new rule applies to every service immediately.

The Collector has several processors that sound similar. Choosing the right one saves a lot of confusion.

A Quick Decision Path

When you are unsure which processor to reach for, ask four short questions. Does the edit concern a fact about the whole producer, such as its environment or version? Use the Resource Processor. Does the edit remove entire items? Use the Filter Processor. Does the edit need conditions, functions, or fields beyond labels? Use the Transform Processor. Does the edit simply add, change, hide, split, or retype a label on individual items? That is the Attributes Processor. Using this order of questions prevents the habit of forcing every job into one favorite tool.

Attributes or Resource?

This is the most common mix-up. The Attributes Processor edits labels on individual items, such as one span’s HTTP route. The Resource Processor edits labels that describe the whole producer, such as the service name or the deployment environment. If you try to add an environment label with the Attributes Processor, it will land on each span, which works but is wasteful and may not be where your backend expects it. Use the Resource Processor for facts about the producer, and the Attributes Processor for facts about individual events.

Attributes or Transform?

The Transform Processor uses a small expression language, called the OpenTelemetry Transformation Language, to describe edits. It can do nearly everything the Attributes Processor can, and much more: it can change span names, edit log bodies, apply conditions, and call helper functions. The price is that rules are written as small statements that take more learning and can be harder to review. The Attributes Processor is declarative: each action is a small structured block that anyone can read. A good guideline is to use the Attributes Processor when your edit fits one of its seven actions, and to reach for the Transform Processor only when you need something more powerful. Many teams use both in the same pipeline.

Attributes or Filter?

If your goal is to make data disappear entirely, such as dropping all health-check spans, use the Filter Processor. If your goal is to keep the data but change what it says, use the Attributes Processor. Filters decide whether an item lives. The Attributes Processor decides what the item’s labels say.

Attributes or Redaction?

The Redaction Processor is built specifically for privacy. It can keep only labels from an allowed list and mask values that match blocked patterns, such as strings that look like card numbers. The Attributes Processor can remove or hash labels you name, but it only knows about the names you list. If you need a safety net that catches sensitive values wherever they appear, including labels you did not know about, a redaction approach is a good complement.

Common jobs that the Attributes Processor does well, described in plain steps.

Recipe 1: Add a Missing Team or Cost Label

Many companies want every piece of telemetry tagged with the team that owns it, so costs can be shared fairly and alerts can be routed. Use an insert action with a fixed value, selected by an include rule that matches the service names of one team. Because insert only fills gaps, services that already set the label keep their own value. Repeat for each team, or use a lookup-style rule set maintained in one place.

Recipe 2: Standardize Names During a Migration

OpenTelemetry’s naming conventions evolve. Some labels have been renamed over time, such as the older and newer names for the HTTP method and status code. During a migration, some services use the old names and others use the new names, which breaks dashboards. You can use the rename pattern, an insert from the old label followed by a delete of the old label, to present a single consistent name to your backend, and retire the rule once all services have upgraded.

Recipe 3: Remove Sensitive Labels

If a label should never leave your network, such as an authorization header value or a database statement that may contain personal data, use a delete action. Select by label name, and remember that delete does nothing when the label is absent, so the rule is safe to apply broadly. Place this early in the pipeline.

Recipe 4: Pseudonymize an Identifier

When you want to count unique users or follow one user’s journey without seeing who they are, use a hash action on the user identifier. This keeps analysis possible while hiding the raw value from people who only look at dashboards. Remember the caution from earlier: for easily guessed values, hashing alone is weak protection, and deleting may be better.

Recipe 5: Split a Compound Label

Sometimes one label holds several facts, such as a path that includes a customer segment and an order number. An extract action with named pattern parts can create separate labels for each fact. After extraction, you can delete the original if it is no longer needed, particularly if it carried risky or high-cardinality text.

Recipe 6: Fix Types

If numbers arrive as text, charts and queries behave oddly. A convert action can turn the text into a whole number or decimal. Apply it only to labels you know hold numeric text, because a failed conversion leaves the value as it was and can hide problems.

Recipe 7: Control Metric Cardinality

If a metric carries a label with thousands of distinct values, such as a user ID, a session ID, or a full path, it can overwhelm your backend. A delete action on that label, applied to metric data points, removes the explosion. Follow the earlier warning about metrics: make sure the remaining labels still tell lines apart, and consider an aggregation step if needed.

Recipe 8: Normalize Values for Better Grouping

Sometimes values themselves are inconsistent: one service writes the region as “eu-west”, another as “EU_WEST”. Charts that group by region show two separate groups for the same place. An update rule can replace known variants with the standard form, selected by the label’s current value. For a small list of variants this is easy. For a large or unpredictable list, consider fixing it at the source or using a more powerful processor with conditions.

Recipe 9: Mark Data for Later Routing

You can use the processor to stamp a label that later steps use as a signal. For instance, an insert rule can mark spans from a particular group of services with a label called “pipeline.tier”. A routing or sampling step further along reads that label to decide where to send the data or how many traces to keep. The Attributes Processor does not route or sample itself, but it prepares the data so that other components can do so cleanly.

Recipe 10: Tag Data by Tenant

In a shared Collector that serves many customers, configure the receiver to keep request metadata, and then use an action whose value comes from the context to copy the tenant identifier onto each item. Downstream, you can route or bill by tenant. Because the value comes from the request rather than from the application’s own data, a customer cannot fake a different tenant by changing their own labels, as long as you overwrite rather than only insert.

An honest look at what this processor gives and what it costs.

When It Is the Wrong Tool

Knowing when not to use the processor is part of using it well. If you need to change a span’s name, the Transform Processor is the right choice. If you need to drop whole items, use the Filter Processor. If you need to add resource-level facts, use the Resource Processor. If you need to combine many data points into one, use an aggregation processor. If you need to decide which traces to keep based on their whole story, use a tail sampling processor. And if the real problem is that an application is capturing sensitive data it should never capture, fix the application. Reaching for the wrong tool tends to create rules that are confusing, fragile, and hard to remove later.

The Key Trade-offs

The first trade-off is central convenience versus source cleanliness. It is quick and powerful to fix labels in the Collector, but the cleanest long-term solution is to fix them where they are born. A healthy practice is to use Collector rules to fix problems now, while also filing requests to correct the sources, and then retire the rules when the sources are fixed. The second is simplicity versus power. The Attributes Processor is simple, but when your needs exceed its seven actions, you move to a more powerful processor with a steeper learning curve. The third is safety versus cost. Running rules on every item costs a little processing time, which is almost always worth the safety, but should be measured on very high volumes.

The processor sees every selected item. At high volumes, small costs add up.

A busy Collector may handle hundreds of thousands of spans, log records, or data points every second. For each selected item, the Attributes Processor performs its actions. Simple actions, such as insert, update, upsert, and delete, are quick operations on a small map. Hash is heavier because it computes a code over the value. Extract and regular-expression selection are the heaviest, because pattern matching can take many steps per value, especially for long strings or patterns with lots of alternatives.

Habits That Keep It Fast

• Select narrowly. An include rule that matches only the services or items that need editing saves work on everything else. Items that are not selected are skipped almost immediately.
• Prefer strict matches. An exact comparison is faster than a pattern.
• Keep patterns simple. Avoid patterns that match very long text or contain nested repetition. Anchor patterns to the start and end of the text when possible.
• Do cheap steps first. If a delete removes a long label that a later regex would have scanned, put the delete first when the original value is not needed.
• Avoid duplicated work. Do not hash the same label twice, and do not extract and then extract again from a result.
• Measure. Use the Collector’s own telemetry to watch processing time and queue sizes before and after you add rules.

Thinking About Capacity

A useful way to plan is to count the number of selected items per second and multiply by the number of actions and their cost. A gateway handling fifty thousand spans per second with five cheap actions each does about a quarter of a million small edits per second, which a modern processor core handles comfortably. If the same gateway runs two regular expressions on a long text label of every span, the cost can be many times higher. Test with realistic data, because the shape of your labels, not just their count, decides the cost.

Scaling Out

Because the processor edits each item independently, it scales easily. Adding more Collector instances behind a load balancer spreads the load, and each instance applies the same rules. The one thing to be careful about is rules that depend on seeing related items together. The Attributes Processor does not need that; it only looks at one item at a time. But other processors in the same pipeline, such as tail sampling, do, and they may force you to route all spans of a trace to the same instance. Place the Attributes Processor before such processors if their decisions depend on the cleaned labels.

Agent or Gateway Placement and Cost

Edits done in an agent, close to the source, reduce the bytes that travel across the network when you delete labels, because data leaves the machine already smaller. Edits done in a gateway are cheaper to maintain, because there are fewer copies of the rules. A common design is to delete obviously unsafe or useless labels at the agent, and to apply the shared naming and tagging rules at the gateway.

Many teams adopt this processor first for one reason: keeping private data out of their monitoring tools.

Telemetry can accidentally contain secrets and personal information. Database statements may include customer names. Web addresses may include session tokens in the query string. Headers may include passwords or access keys. Error messages may include account numbers. Once such data lands in a monitoring product, it is visible to many people, may be stored for months, and may be copied into backups. Removing it before it leaves your network protects your customers and reduces your legal and reputational risk.

Delete, Hash, or Redact?

For secrets such as passwords and keys, always delete. There is no reason to keep even a scrambled version. For identifiers you need to count, such as user IDs, hash may be acceptable, if the values are hard to guess and the hash recipe is strong. For free text that may contain anything, a rule list of known names is not enough; use a redaction approach that scans values for risky patterns, and consider removing the label altogether.

Defense in Depth

The best protection uses layers. At the source, instrumentation can be configured not to capture risky data in the first place, such as turning off capture of database parameters or request bodies. At the agent, a rule set removes known sensitive labels. At the gateway, another set enforces company-wide policy and a redaction step catches anything unexpected. At the backend, access controls limit who can see what remains. If one layer fails, the others still protect the data.

Allow Lists Beat Block Lists

A block list says “remove these specific labels”. It protects only against dangers you already know. An allow list says “keep only these labels and remove everything else”. It protects against unknown labels, but it risks removing labels you actually need. For the strictest environments, an allow list approach, often built with a redaction processor in addition to the Attributes Processor, gives the strongest guarantee.

Privacy Laws and Practical Duties

Many regions have laws about personal data, and these laws often apply to telemetry as much as to databases. A web address with an email in it, an IP address in a log line, or a user ID in a trace may all count as personal data. While this guide is not legal advice, the practical lesson is clear: know what labels your telemetry contains, decide which are needed, remove or protect the rest, and write down your choices. The Attributes Processor gives you a concrete, auditable way to carry out those choices, because the rules are written in plain configuration that a reviewer can read.

Protecting the Rules Themselves

The Collector configuration is a security control. Anyone who can edit it can turn off privacy rules or add labels that leak data. Store it in version control, require review for changes, and restrict who can deploy it. When you hash values, do not store secret salts or keys in plain text in the configuration, and remember that changing the hash recipe changes every code, which breaks comparisons with older data.

When labels do not look the way you expect, a calm method finds the cause quickly.

Seeing What the Processor Sees

The easiest way to check your rules is to look at the data before and after. The Collector has a debug exporter that prints items it receives, including their attributes, to the Collector’s own output. You can add it to a pipeline temporarily and compare an item as it arrives with the item as it leaves. For a controlled test, send a few sample items through a small test Collector with the same rules, and look at the result. Test with items that have the label, items that lack it, and items with unusual values, because the three cases behave differently.

Common Symptoms and Causes

Two Worked Troubleshooting Stories

Story one: the label that never arrived. A team wrote an insert rule to add a team label, but the label never appeared on their dashboards. They checked the pipeline and found the processor was listed. They checked the selection rules and found a regular expression meant to match service names starting with “checkout”, but the actual service names started with “shop-checkout”. The pattern was not anchored the way they believed, so no items were selected. Changing the rule to match the real names fixed it. The lesson: test selection rules against real names copied from data.

Story two: the vanished label. Another team wrote a rename as a delete followed by an insert from the old label, in that order. After deploying, both the old and new labels were missing. The delete ran first, so the later insert had nothing to copy. Swapping the order, with the insert first and the delete second, solved it. The lesson: walk through your actions by hand, in order, and ask what each one sees.

A Methodical Order

First, confirm the processor is actually listed in the pipeline for the signal you care about, because defining a processor without listing it does nothing. Second, check the selection rules: is the item you are testing actually selected? Third, look at the actions in order, and walk through them by hand with the item’s labels. Fourth, check for exact names, because label keys are case sensitive and a small difference makes a rule miss. Fifth, check whether another processor, before or after, is changing the same labels. Finally, compare the debug output at each stage.

Testing Rules Before Production

A sound habit is to keep a small set of sample items that represent real data: one with the label present, one with it missing, one with an odd value, and one that should not be selected at all. Run them through a test Collector with your rules and check the output against what you expect. Automate this check in your build pipeline, so that a typo in a rule fails the build instead of silently changing production data. Because the processor is deterministic, meaning the same input always gives the same output, these tests are easy to write and very reliable.

Rolling Out Changes Safely

Deploy rule changes gradually. Start with one agent or one Collector instance, watch the output and the Collector’s own metrics, and only then roll out to the rest. Keep the previous configuration at hand so you can revert quickly. For deletions of labels used by dashboards or alerts, announce the change first, because removing a label can silently break a chart that someone depends on.

Watching the Collector Itself

The Collector exposes its own metrics, such as how many items each stage received and refused, how long processing takes, and how full its queues are. After adding or changing rules, watch these for a sudden rise in processing time or refused data. Alert on configuration reload failures, so you learn right away if a typo stops a new rule from loading. And keep a record of which configuration version is running, so that when labels change on a dashboard, you can tell whether a rule change was the cause.

Habits that keep your rules healthy, and habits that cause trouble later.

Patterns That Work

• Small, named rule sets. Use separate named instances for separate purposes, such as one for privacy, one for naming, and one for team tags.
• Narrow selection. Apply each rule only to the services or items that need it.
• Cleaning before deciding. Put label edits before filters and samplers that depend on those labels.
• Privacy first. Place deletion and hashing of sensitive labels early in the pipeline.
• Configuration as code. Keep rules in version control, review changes, and test them against sample data.
• Document the why. Next to each rule, record who asked for it, what problem it solves, and when it can be removed.
• Fix sources too. Treat each rule that repairs a bad label as a request to fix the origin.

Anti-Patterns to Avoid

Governing Rules Across Many Teams

In a large company, the Collector rules belong to a platform team, but the data belongs to many application teams. This split can cause friction if rules change without warning. A healthy arrangement has three parts. First, a published list of which labels the platform adds, renames, or removes, so application teams know what to expect. Second, a simple request process, so a team that needs a new rule can ask and get an answer quickly. Third, a regular review in which old rules are retired once the underlying problem is fixed. With these in place, the Attributes Processor stays a helpful shared service instead of becoming a mysterious force that changes data behind everyone’s back.

A Short Checklist

• Is the processor listed in every pipeline where its rules should apply?
• Is the order of processors and the order of actions what you intended?
• Do selection rules limit edits to the data that needs them?
• Are sensitive labels deleted early, and are hashed values truly hard to guess?
• Have you checked metrics for label collisions after deleting labels?
• Are configuration changes reviewed, versioned, and tested on sample data?
• Does each rule have an owner, a reason, and a plan for removal?

Common situations that show the processor at work. These are illustrative patterns frequently seen in production systems.

Short answers to questions that appear again and again.

If you remember only a few things, remember these.

The Attributes Processor is the Collector’s label editor. It lets a central team add, change, remove, hide, split, and retype the labels on traces, logs, and metrics as they pass through, without touching application code. It is small, predictable, and easy to read, and that is why it is one of the most commonly used processors in real deployments.