A gauge is a metric that reports the current value of something that can go up and down. It is a snapshot, not a running total.

First, what is a metric?

A metric is a number that is measured over time, such as “requests per second” or “memory in use”. Unlike a log, which tells a story in words, or a trace, which follows one request, a metric squeezes a lot of activity into a small number. That makes it cheap to store and perfect for charts and alerts.

Now, the gauge

A gauge is the metric type for a value that is a level, not a count of events. Think of a thermometer. It does not add up all the heat it has ever felt. It simply shows the temperature now. In OpenTelemetry, a gauge records a measurement such as “the temperature is 21.5 degrees” or “CPU is 63 percent busy”, and the system sends that number onward, together with the time it was taken and a few labels that say what it describes.

One property is the heart of the gauge idea: its values are non-additive. This means that adding two readings together does not make sense. If two rooms are each 21 degrees, the combined temperature is not 42 degrees. If you remember only one thing from this guide, remember this: use a gauge when summing the values would be meaningless.

Where the gauge lives

Like every OpenTelemetry metric, a gauge is created through the SDK. Your code asks a meter to create an instrument. The instrument is the object you use to report numbers. The SDK then collects those numbers on a schedule and sends them to a backend, a program that stores them and draws charts. You will see each of these steps in detail in the chapters ahead.

The gauge is one member of a small family of metric instruments. Seeing the whole family makes it much easier to know when to pick the gauge and when to pick something else.

The instruments at a glance

OpenTelemetry offers a few instrument types, and each one fits a different shape of data. Most of them come in two styles. A synchronous instrument is one you call from your own code at the moment something happens. An asynchronous (or observable) instrument is one where you register a small function, called a callback, and the SDK calls it when it is time to collect.

A decision path

The diagram below turns the table into a path you can follow with a few yes-or-no questions.

flowchart TB
    Q["What are you measuring?"] --> A{"Counting events that only go up?"}
    A -- Yes --> C["Counter"]
    A -- No --> B{"A level that moves up and down, and adding readings makes sense?"}
    B -- Yes --> U["UpDownCounter"]
    B -- No --> D{"Do you need the spread of many values?"}
    D -- Yes --> H["Histogram"]
    D -- No --> G["Gauge (current value, adding makes no sense)"]

Start at the top. If you are counting things that happen, such as orders or errors, use a counter. If you track a quantity that rises and falls but where totals still make sense, such as the number of items waiting in a queue, use an up-down counter. If you care about the shape of many measurements, such as how long requests took, use a histogram. Everything left over, the levels and readings where adding is meaningless, belongs to the gauge.

Beginners most often mix up the gauge and the up-down counter, and sometimes the gauge and the histogram. Let us separate them carefully.

Gauge or counter?

A counter only goes up. It counts things that happened, such as page views. If you restart the program, it starts again at zero. Its most useful question is “how fast is it growing?”, which is a rate. A gauge is not about growth. It is about the level. Asking for the “rate of a temperature” almost never makes sense, while asking for the “rate of orders” always does.

Gauge or up-down counter?

This is the subtle one. Both can rise and fall. The difference is whether adding makes sense. The number of items in a queue on server A and on server B can be added to give the total waiting. That is additive, so an up-down counter fits. The CPU utilization of server A and server B cannot be added into anything useful. That is non-additive, so a gauge fits. In OpenTelemetry’s standard naming rules, system memory usage in bytes is modeled with an up-down counter because the sum across machines is meaningful, while CPU utilization is modeled as a gauge.

Gauge or histogram?

A gauge keeps only the latest value. A histogram keeps the spread of every value it saw, sorted into buckets. If you record request durations in a gauge, you see only the last request, and everything before it is lost. If you record them in a histogram, you can find the median and the 99th percentile. Use the gauge for a state, and the histogram for a distribution of events.

You can feed a gauge in two different ways. Choosing the right one is mostly about who knows when the value changes.

The synchronous gauge: you push when it changes

With a synchronous gauge, your own code calls a record function whenever the value changes. Imagine a smart thermostat that reacts to a new temperature reading and immediately tells the gauge, “it is now 22.1”. The SDK remembers the most recent value for each set of labels. When the time comes to export, it sends the latest one. This style fits cases where your code already knows the moment of change, such as a setting a user just changed.

The observable gauge: the SDK asks when it needs to know

With an observable gauge, you give the SDK a small function called a callback when the instrument is created. During every collection cycle, the SDK calls the callback, and the callback reads the current value from wherever it lives, such as the operating system, a sensor, or a pool of connections, and returns it. Nobody has to call anything when the value changes. The SDK checks only when it plans to export. This style fits things that exist independently of your code, such as CPU load or free disk space.

sequenceDiagram
    participant App as Application Code
    participant SG as Synchronous Gauge
    participant OG as Observable Gauge
    participant R as Metric Reader
    participant Sys as Sensor or System
    App->>SG: record 22.1 when the value changes
    Note over SG: SDK keeps only the latest value
    R->>SG: Collect (on a timer)
    SG-->>R: Latest recorded value
    R->>OG: Collect (on a timer)
    OG->>Sys: Callback reads current value
    Sys-->>OG: 63 percent
    OG-->>R: Observation 63

What does a gauge actually carry? Let us open one up and look at each part.

The data point in the wire format

When the SDK sends a gauge through OTLP, the OpenTelemetry wire format, the metric arrives as a record of type “gauge”, containing a list of data points. Each data point holds the number, the timestamp, and the attributes. Notice what is missing. A gauge data point has no “temporality” and no “monotonic” flag, which belong to counters and similar types. A gauge simply says: “at this time, for these labels, the value was this”.

The gauge is simple, but choosing the right things to put in it is a skill. Here are good fits, and some tempting wrong fits.

Good fits

Tempting wrong fits

Let us follow one gauge reading from your code to the network. Knowing these steps explains almost every surprising thing you might see on a chart.

The big consequence: values between collections are lost

Because the gauge keeps only the last value, anything that happens between two collections and is then replaced never leaves the program. If CPU jumps to 99 percent for five seconds and falls back to 40 percent before the next collection, the gauge reports 40. The spike is invisible. This is not a bug. It is how a gauge is defined: “the value at the moment of reading”.

The callback is the single most important part of an observable gauge, and the place where most bugs hide. Let us watch one in action.

sequenceDiagram
    participant T as Timer (every 60 seconds)
    participant R as Periodic Metric Reader
    participant S as SDK
    participant CB as Your Callback
    participant OS as Operating System
    participant E as OTLP Exporter
    T->>R: Time to collect
    R->>S: Collect all instruments
    S->>CB: Invoke callback
    CB->>OS: Read CPU utilization
    OS-->>CB: 0.63
    CB-->>S: Observation 0.63 with attributes
    S-->>R: Metric data with gauge data points
    R->>E: Export batch

Read the figure from top to bottom. A timer fires. The reader asks the SDK to collect. The SDK runs your callback, the callback reads the real value, and returns an observation, which is a value plus its attributes. The SDK packages everything into metric data, and the reader hands it to the exporter. The whole cycle repeats at every interval.

Rules for writing a good callback

One callback, many readings

A single callback can return many observations, each with different attributes. For example, one callback can report the temperature of every room in a building, tagging each reading with the room name. Some SDKs also allow one callback to feed several instruments at once, which is useful when one system call returns several related numbers together.

Three technical words, aggregation, temporality, and view, decide how measurements turn into exported metrics. For a gauge, the story is happily short.

Aggregation: last value wins

Aggregation is the way many measurements are combined into one number. For counters, the usual aggregation is a sum. For histograms, it is bucket counts. For a gauge, the default is the last value, which means that when several measurements arrive with the same attributes during one cycle, only the latest is kept. This matches the meaning of a gauge: the newest reading replaces the older one.

Temporality: not needed

Temporality describes whether exported numbers are running totals since start (cumulative) or changes since the last export (delta). It matters for counters and histograms. It does not matter for a gauge, because a gauge reports a level, and a level has no “total so far” or “change since last time”. This is one less thing to configure, and one reason gauges are friendly to many backends.

Views: powerful but handle with care

A view is a rule you set in the SDK to reshape a metric before it is exported. It can rename the metric, filter its attributes, or choose another aggregation. With gauges, one use deserves a warning. If a view removes an attribute, then several series that were separate become one, and the gauge keeps only the last value among them.

The SDK is only the start of the journey. Where does a gauge reading go after it leaves your program, and what happens to it there?

flowchart LR
    I["Gauge instrument in your code"] --> M["Measurement"]
    M --> V["View (optional)"]
    V --> AG["Last value aggregation"]
    AG --> MR["Periodic Metric Reader"]
    MR --> ME["OTLP Metric Exporter"]
    ME --> CO["Collector (agent or gateway)"]
    CO --> BE["Metrics Backend"]
    BE --> DB["Dashboards and Alerts"]

The stages of life

How backends treat a gauge

Many backends have a gauge idea of their own. In Prometheus-style systems, an OpenTelemetry gauge becomes a Prometheus gauge, a value that can go up or down. In query languages, you chart gauges directly, or use functions such as average, minimum, and maximum over a time window. You would almost never take the “rate” of a gauge, since a rate is meant for things that only grow.

In production you rarely have one copy of a service. You have dozens. How do gauges behave when many copies report the same metric?

flowchart LR
    P1["Pod 1 (gauge: cpu utilization 0.40)"] --> CO["Collector"]
    P2["Pod 2 (gauge: cpu utilization 0.85)"] --> CO
    P3["Pod 3 (gauge: cpu utilization 0.55)"] --> CO
    CO --> BE["Backend stores three separate series"]
    BE --> Q["Query: average or maximum, never the sum"]

Each copy needs its own identity

The resource attached to each copy should contain an attribute that tells the copies apart, such as a service instance ID. Without it, three gauges with identical labels would collide in the backend, and they would overwrite each other. You would see a jittery line, jumping among the three values, that tells the truth about none of them.

Combine them at query time

Once the backend holds one series per copy, you decide how to combine them for the question at hand. To ask “is any copy overloaded?”, use the maximum. To ask “how busy is the fleet in general?”, use the average. To ask “which copy is the problem?”, look at each series on its own. The sum of CPU utilization percentages across copies is rarely useful, since it does not describe any real thing.

Attributes make a gauge useful, and they are also the fastest way to make it expensive. The word to know is cardinality.

What is cardinality?

Cardinality is the number of different attribute combinations a metric has. A gauge for room temperature with a “room” attribute and thirty rooms has a cardinality of thirty. Each combination becomes its own series in the backend, with its own storage and indexing cost. Cardinality is the main cost driver of metrics.

Rules of thumb

• Use attributes that have a small, known set of values.
• Never use values that grow with traffic, such as user IDs, session IDs, or full URLs.
• Prefer stable names, such as the route template “orders by ID”, over actual paths.
• Remember that each attribute multiplies the others. Ten rooms times ten devices times five regions already makes five hundred series.

A gauge that says “42” is almost useless. Forty-two what? Names and units turn a bare number into information.

Always set a unit

The unit says what the number is measured in. OpenTelemetry follows a standard code system for units, so values like seconds, bytes, and degrees Celsius have agreed short codes. For plain ratios, such as “CPU is 63 percent busy”, the convention is to report a fraction between zero and one, for example 0.63, with the unit “1”, instead of a number between zero and one hundred. Charts and tools can then show it as a percentage, and mixing up scales becomes less likely.

Names tell the story

A good metric name is lowercase, uses dots to separate parts, and reads like a short description of the thing: the area first, then the quantity. The semantic conventions already define names for common things such as CPU, memory, disk, and network. If one fits, use it, because dashboards and alerts written by other people will understand your data right away.

Let us run a small experiment on paper. A service has an observable gauge for CPU utilization, and the SDK collects once per minute.

What really happened inside one minute

Imagine that, during one minute, the real CPU load changed like this, measured every ten seconds. These are the true values, which the gauge cannot see.

What the gauge reports

At second 60, the SDK runs the callback, and the callback returns the current value, about 40 percent. That is the only number exported for this minute. The chart will show a calm 40 percent line, and nobody will ever know that for twenty seconds the machine was almost fully busy.

Compare this with the real picture. The average over the minute was about 59 percent (the six values add up to 355, and 355 divided by 6 is about 59). The maximum was 97 percent. The gauge told the truth about one instant and said nothing about the rest.

Three ways to see more

Gauges are the natural fuel for dashboards and alerts about health and capacity. A few habits make those alerts calm instead of noisy.

flowchart LR
    G["Gauge: disk fullness ratio"] --> BE["Metrics Backend"]
    BE --> RU{"Rule: above 0.9 for 10 minutes?"}
    RU -- No --> OK["No alert"]
    RU -- Yes --> AL["Alert sent to on-call engineer"]
    AL --> IN["Engineer opens dashboard, logs, and traces"]

Good alert habits

• Use a duration. Alert when the value stays above a limit for several minutes, not on a single reading. This avoids waking someone for a harmless blip.
• Pick the right combination. For fleets, alert on the maximum if one bad copy matters, or on the average if only a general problem matters.
• Alert on missing data too. If a gauge stops reporting, the chart simply ends. Add a rule that fires when expected data is absent.
• Watch trends, not only levels. A disk that fills by two percent per hour will be full in a day, even though it is fine now. Use a prediction function for such cases.
• Add context to the alert. Include the service name, instance, and a link to the right dashboard.

Connecting gauges to the other signals

A gauge tells you that something is off. Traces and logs help you find out why. They are connected through shared resource attributes, such as the service name and instance ID, and through time. When a CPU gauge climbs at 10:05, you can open traces and logs from the same service and instance around 10:05 to see what the code was doing. Gauges do not carry trace IDs on their values, so the link is made by labels and time.

A single number looks harmless, yet a collection of gauges describes the health, size, and habits of your systems. Protect it accordingly.

A protective checklist

• Review every attribute and ask whether it is safe to show to everyone who can see dashboards.
• Scrub or drop sensitive labels in the Collector before data reaches storage.
• Separate production and test metrics so test values cannot trigger production alerts.
• Control who can edit alert rules, since changing a threshold can silence an alarm.

Gauges are among the cheapest signals you can produce, but a few details can still hurt, and some failure behaviors are surprising.

What costs time and memory

Choosing the collection interval

The collection interval is a trade between detail and cost. A common default is about one minute, which suits slow-moving values like disk usage. Faster-changing values, like CPU on a busy machine, may justify ten to fifteen seconds. Slower interval means fewer points and bigger gaps. Faster interval means more detail and more cost. Pick based on how quickly the value can change and how quickly you need to react.

Gaps are permanent

Here is a reliability detail that surprises many people. A cumulative counter heals itself: if one export is lost, the next one still holds the full running total, so the chart recovers. A gauge cannot heal. If an export is lost because the Collector was down, the readings for that interval are simply gone, since they were instants in time. Your charts will show gaps.

The gauge is simple and honest, and its simplicity is both its strength and its limit.

Choices to make on purpose

Teams who run metrics at scale tend to settle on the same few habits. Here they are, along with the traps that keep catching newcomers.

Patterns worth copying

Anti-patterns to avoid

Keep this short list close. It prevents most of the trouble that beginners meet with gauges.

Common mistakes and their fixes

First, a made-up story that shows gauges at work. Then, a look at where gauges already show up across the industry.

Your gauge will be translated at least twice on its way to a chart. Knowing what each translation does helps you understand odd-looking results.

The OTLP shape

In OTLP, the standard wire format, a metric is one of several data types: sum, gauge, histogram, exponential histogram, or summary. A gauge metric holds a list of data points. Every data point has a number (whole or decimal), a time, and a set of attributes. It has no running-total flag and no aggregation temporality, because neither idea applies to a level.

A close cousin: the non-monotonic sum

An up-down counter does not travel as a gauge. It travels as a sum that is marked as not “monotonic”, which means it is allowed to decrease. That difference matters at the other end. A backend that sees a sum knows adding is allowed. A backend that sees a gauge knows it is not. Your choice of instrument therefore sends a message to every later system about how the numbers may be combined.

How the pieces map to Prometheus

Names can change in translation. Dots in OpenTelemetry names are turned into underscores, and some systems add suffixes for units. If you search for your metric and cannot find it, try the translated name first.

Here are common things teams want to measure, with a sensible way to model each. Use it as a starting point whenever you are unsure.

How to read the cookbook

Notice a pattern: the “combine” column almost always says maximum, minimum, or average for gauges, and sum only for the up-down counter at the end. That one pattern captures the heart of this whole guide. Gauges are levels you compare. Counters and up-down counters are quantities you add.

Sooner or later a chart will look strange. Work through the stages of the journey in order, and the cause usually appears quickly.

Walk the path from end to start

Symptoms and likely causes

Quick answers to the questions people ask most often about gauges.

You started with a car dashboard needle. You now know how that simple idea is built into OpenTelemetry, and how to use it without being fooled.