Not everything in a running system only ever grows.

Applications are full of quantities that rise and fall naturally. A web server handles many requests at once, and the number of requests being processed right now changes every millisecond. A job queue grows when work arrives and shrinks when workers finish. A database connection pool lends out connections and gets them back. A shopping cart gains and loses items. A game server gains and loses players.

Engineers need to watch these numbers, because trouble often shows up as a number that stays too high for too long. A queue that never shrinks means workers are stuck. A count of active requests that keeps climbing means the service is slowing down. A pool with every connection lent out means new users must wait.

A simple counter that only grows cannot describe these situations. Imagine trying to describe the water level in a bathtub using only a tally of how much water ever flowed in from the tap, ignoring what drained out. The tally would be technically correct and practically useless. We need an instrument that can move in both directions.

A short refresher on the surrounding vocabulary makes everything easier.

OpenTelemetry, often called OTel, is an open-source project that defines how software describes its own behavior. It is vendor neutral, which means no single monitoring company owns it. It handles three kinds of data, called signals: traces, metrics and logs. This guide lives in the world of metrics, which are numbers measured over time.

The family of instruments

OpenTelemetry offers several instruments, each shaped for a different kind of question. The ones you will meet most often are the Counter, the UpDownCounter, the Gauge and the Histogram. Each of them also has a version where the library reads the value for you through a callback, called an asynchronous or observable instrument. We will compare them carefully in a later chapter.

An UpDownCounter is an instrument that records additions and subtractions to a running total.

Let us define it carefully. An UpDownCounter in OpenTelemetry is a metric instrument used to record changes to a value that can both increase and decrease over time. You use it by calling an add operation whenever something changes, passing a positive number when the value grows and a negative number when the value shrinks. The library keeps the running total, which represents the current level of whatever you are tracking.

The name tells the story: it is a counter that can go up and also go down. Compared with the regular Counter, which accepts only non-negative additions and therefore never decreases, the UpDownCounter accepts negative additions too. In the language of the specification, the regular Counter is monotonic, meaning it never decreases, while the UpDownCounter is non-monotonic.

The two instruments look alike but answer very different questions.

The easiest way to understand the UpDownCounter is to place it next to its famous sibling, the Counter. Both are sums built from additions. The difference lies in what they promise and in what question they answer.

Pairing them together

Many real systems use both on the same event. For example, a web service can use a regular Counter to count every request ever received, and an UpDownCounter to track how many requests are in progress at this moment. One tells you how busy the service has been, the other tells you how loaded it is right now.

Good UpDownCounters measure how much of something exists at a moment.

The classic use of an UpDownCounter is any quantity that is increased by an event and decreased by an opposite event. When you can name the up event and the down event, you have found a candidate.

Knowing the limits prevents the most common beginner mistakes.

The UpDownCounter is flexible, which makes it tempting to use everywhere. But some quantities are better served by other instruments. Picking the wrong one produces confusing charts and sometimes wrong numbers.

This is the comparison that confuses beginners most, so let us settle it clearly.

Both an UpDownCounter and a Gauge can describe a number that moves up and down. So when should you use which? The answer depends on how the number is known and whether it makes sense to add values from different sources.

With an UpDownCounter, you report changes: one more arrived, one left. The library builds the balance. The values from different instances of your service can be added together, because they are all balances of the same kind of thing. If three servers each report four requests in progress, the whole system has twelve.

With a Gauge, you report the current reading directly: the temperature is now twenty-two degrees. Readings of this kind often do not make sense to add. If three rooms each report twenty-two degrees, the total of sixty-six degrees is meaningless. Gauges are for such non-additive readings.

A single decision path makes the choice almost automatic.

flowchart TD
  Q1{"What kind of number is it?"}
  Q1 -->|"Total of events, only grows"| C["Counter"]
  Q1 -->|"Balance built from ups and downs"| U["UpDownCounter"]
  Q1 -->|"Current reading, not additive"| G["Gauge"]
  Q1 -->|"Spread of many values such as latency"| H["Histogram"]
        

There are two ways to feed the balance, depending on who notices the change.

The regular UpDownCounter is synchronous. Your code is in charge and calls add at the moment each change happens. Use it when your own program performs the up and down events, such as accepting and finishing requests.

The second style is the asynchronous UpDownCounter, also called the observable UpDownCounter. You register a small function called a callback. Whenever the library is about to collect metrics, it calls your function, and your function reports the current total. Use it when the balance already lives somewhere else and you merely want to read it, for example the number of items in an external queue that the library of that system already tracks.

The biggest danger of an UpDownCounter is a balance that quietly drifts away from reality.

Because an UpDownCounter is built from changes, its accuracy depends on every up event being matched by exactly one down event. If a request adds one when it starts but an error path forgets to subtract one when it ends, the balance will creep upward forever, even when the system is idle. A chart of requests in progress might show fifty when the true number is zero. This kind of drift is the most common bug with this instrument.

sequenceDiagram
  participant R as Request
  participant U as UpDownCounter
  R->>U: Start: add 1
  Note over U: Balance goes up
  R->>R: Do the work
  alt Work succeeds
    R->>U: End: add minus 1
  else Work fails
    R->>U: End: add minus 1 as well
  end
  Note over U: Balance returns to where it was
        

How to stay safe

Labels on an UpDownCounter need extra care compared with a regular Counter.

Like other instruments, an UpDownCounter lets you attach attributes, which are small key and value labels such as the route being served or the queue name. The library keeps a separate running balance for every unique combination of attribute values, called a time series.

Here is the trap. If you add one with the attribute route equal to checkout, but later subtract one with a different attribute, say route equal to payment, the two balances will not cancel each other. The checkout series will be stuck one above zero and the payment series one below zero. Neither tells the truth.

flowchart LR
  A["Start: add 1 with route checkout"] --> B["Series checkout is 1"]
  C["End: add minus 1 with route payment"] --> D["Series payment is minus 1"]
  B --> E["Both series are wrong forever"]
  D --> E
        

Cardinality still matters

As with any metric, avoid attributes with huge numbers of possible values, such as user identifiers or request identifiers. Each unique combination creates a new series, which costs memory and money. For an UpDownCounter there is an extra reason to be careful: a series with a stale non-zero balance can linger for a long time.

Let us follow a single change from your code all the way to a dashboard.

Understanding the journey helps you reason about delays and surprises. Here is what happens when a request starts and later ends.

sequenceDiagram
  participant App as Application Code
  participant SDK as SDK Aggregator
  participant R as Metric Reader
  participant E as Exporter
  participant B as Backend
  App->>SDK: Add 1
  App->>SDK: Add 1
  App->>SDK: Add minus 1
  Note over SDK: Balance is now 1
  R->>SDK: Collect on timer
  SDK-->>R: Current balance
  R->>E: Hand over snapshot
  E->>B: Send metrics
        

The balance is summarized as a sum that is marked as allowed to go down.

OpenTelemetry separates the act of recording from the way recorded values are summarized. For an UpDownCounter, the default summary is a Sum, and it is marked as non-monotonic. That mark is a message to every backend saying: this value can go down, so do not treat a decrease as a reset, and do not compute a rate of growth from it.

This is the reason the UpDownCounter exists as a separate instrument rather than a flag on the regular Counter. The mark changes how the data is understood everywhere downstream. A backend that sees a drop in a monotonic sum assumes a restart and adjusts. A backend that sees a drop in a non-monotonic sum accepts it as real.

The way a total is reported matters even more for a balance than for a regular Counter.

When a sum is exported, it can be described in one of two styles, called temporality. Cumulative style reports the full running balance since the program started. Delta style reports only the change since the last report.

Look at the cumulative column: each report directly answers how many are there right now. With the delta column, a backend must add up every past delta to reconstruct the balance, and a single lost report would make the balance wrong from then on. For this reason, cumulative reporting is the natural fit for UpDownCounters, and the OpenTelemetry specification suggests cumulative as the default for this instrument. Some backends that prefer delta for other instruments still keep cumulative for balances.

Unlike a regular Counter, you chart the value itself, not its rate.

For a regular Counter, the raw total is rarely interesting, and people chart its rate of growth. For an UpDownCounter, it is the opposite. The value itself is the answer. A line chart of requests in progress shows exactly how loaded the system is. Taking a rate of an UpDownCounter usually produces confusing numbers that mix up arrivals and departures.

Useful alerts

Good alerts for an UpDownCounter watch for a balance that stays beyond a sensible level for a sustained period. A queue length above a threshold for ten minutes is meaningful. A single moment above the threshold is usually just a burst. Another valuable alert is for a balance that fails to return to a low value during quiet periods, which can reveal the missed-subtraction bug described earlier.

A good UpDownCounter introduces itself clearly so strangers can understand it.

When you create an UpDownCounter, you give it a name, a unit and a description. These small details matter greatly, because the person reading a chart months later will not remember what you meant.

Name a balance after the thing that is present, such as active requests or queue length, not after the event of adding. Keep names stable, because renaming breaks dashboards and alerts. Follow the semantic conventions whenever one exists, so that your numbers match those of other teams. And create each instrument once at program start and reuse it everywhere, rather than recreating it for every event.

Seeing the patterns in familiar systems makes the idea concrete.

The in-flight request pattern

A web service adds one when a request arrives and subtracts one when the response is sent. The balance is the number of requests currently being handled. A steady low number means health. A steadily rising number signals slowness, because new requests arrive faster than old ones finish.

The queue pattern

A producer adds one when it puts a message on a queue, and a consumer subtracts one when it takes the message. The balance is the backlog. A growing backlog tells you the consumers are too few, too slow or stuck.

The pool pattern

A connection pool adds one when a connection is lent out and subtracts one when it comes back. Compared with the pool’s size, the balance shows how close the system is to running out of connections, a classic cause of mysterious waits.

The session pattern

A chat or game service adds one on login and subtracts one on logout or timeout. The balance is the number of people online, which is useful for capacity planning and for noticing unusual drops after a release.

flowchart LR
  P["Producer"] -->|"add 1"| Q["Queue balance"]
  Q -->|"add minus 1"| W["Worker takes a message"]
  Q --> M["Exported as queue length"]
        

A short checklist that saves hours of confusion later.

Every design choice has a price, and the UpDownCounter is no exception.

Balancing simplicity and correctness

The UpDownCounter is simple to use but unforgiving to sloppy code. The more places your program can start something, the more places must also end it. Teams that wrap the pair in a single helper, or that use the asynchronous style to read a balance maintained elsewhere, avoid most of the pain. When a trustworthy external reading exists, the observable form or a Gauge may be the safer choice.

Seeing how teams use UpDownCounters makes the ideas concrete.

It is a metric instrument that records additions and subtractions to a running balance, so it can describe values that rise and fall, such as requests in progress.

A Counter only goes up and tells you how many events have happened in total. An UpDownCounter can also go down and tells you how much exists right now.

It means the value is allowed to decrease as well as increase. Backends use this mark to avoid treating a drop as a reset.

Use a Gauge when you read a current value directly and adding values from different sources would be meaningless, such as temperature or a percentage.

Not in the synchronous style. You report only changes, such as plus one or minus one, and the library keeps the balance. In the asynchronous style you report the current total through a callback.

Most likely some code path adds but never subtracts, often an error, timeout or cancellation path. Make sure every start has a guaranteed matching end.

The attributes used when adding differ from those used when subtracting, so the two changes landed in different series. Use identical attributes for both.

It starts again from zero, which is usually correct because a new process has nothing in flight.

Usually no. The value itself is the answer. A rate would mix arrivals and departures and is hard to interpret. Use a Counter if you want a rate.

Cumulative is the natural fit, because each report directly shows the current balance and a lost report does not corrupt later ones.

Yes. Balances of the same kind of thing are additive, so the sum across instances is the load on the whole system.

Very little. Each change is a tiny in-memory operation, and the heavy work of exporting happens rarely and off the main path.

We began at a library desk where a single sheet records how many books are out right now: a plus when one leaves, a minus when one returns. An UpDownCounter in OpenTelemetry is exactly that sheet. It is a cheap, simple instrument for balances such as requests in progress, queue length, active connections and players online. Your code adds and subtracts, the SDK keeps the running balance, and a reader exports it on a schedule as a non-monotonic sum, usually in cumulative style. Choose it when the number rises and falls by steps, pair every up with a matching down, keep attributes identical on both sides, and chart the value itself. Choose a Counter for ever-growing totals, a Gauge for non-additive readings, and a Histogram for spreads of values.