Prometheus / Basic: collection and time-series meaning / Lesson 3

Counters, gauges, and exposition contracts

Choose a metric type from quantity semantics, read a text exposition fragment, and separate declared type metadata from the query you must apply.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Compare counters and gauges with distributions.
Interpret HELP and TYPE declarations.
Review units, naming, and exposure safety.

Choose the type before writing a query

A counter accumulates events or a nonnegative quantity and can reset when its process restarts. A gauge represents a current value that may increase or decrease, such as in-flight requests. Histograms and summaries represent distributions with different aggregation properties explored later. Do not apply rate mechanically to every numeric series: a decreasing queue depth is not a counter reset. Write the quantity, unit, update boundary, and intended aggregation before choosing an instrument. A syntactically accepted query cannot rescue an instrument that counts attempted writes while its documentation promises committed writes.

Read metadata and samples separately

The text fragment declares a counter and a gauge with HELP and TYPE comments, then supplies synthetic samples. The declaration describes intent; it does not make an inappropriate query meaningful. The fixed course baseline concentrates on float samples and classic histogram series rather than assuming every protocol capability is interchangeable. Exposition has escaping, encoding, content-type, and consistency rules that a supported client library should handle in real code. An endpoint can respond at HTTP level while malformed or incompatible content still prevents a useful scrape. This fragment is not a complete monitored application.

text Synthetic text exposition metadata

# HELP warehouse_requests_total Eligible warehouse API attempts.
# TYPE warehouse_requests_total counter
warehouse_requests_total 42
# HELP warehouse_in_flight Current warehouse API work.
# TYPE warehouse_in_flight gauge
warehouse_in_flight 3

The counter describes accumulated attempts and the gauge current work. The fragment is illustrative and has not been served, scraped, or protocol-validated.

Compare accumulated and current values

The offline model increments a completed-operation count and changes current work through starts and finishes. The final counter is two while current work is one. These quantities answer different questions and should not be subtracted as if they formed one population. The model omits concurrency, process restarts, and client-library synchronization; it proves only the shown state transitions. A real instrument must handle its supported execution model and avoid high-cost label creation on hot paths. Keep failed operations and cancellation semantics explicit instead of deciding their classification accidentally at one increment statement.

python Offline counter and gauge state model

completed = 0
in_flight = 0
for action in ["start", "start", "finish", "start", "finish"]:
    if action == "start":
        in_flight += 1
    else:
        in_flight -= 1
        completed += 1
assert in_flight >= 0
print("completed_total", completed)
print("in_flight", in_flight)

Expected output

completed_total 2
in_flight 1

Only the fixed action list is processed. No client library is imported and no concurrent or instrumented application is executed.

Make names and units support interpretation

Use clear quantity names and consistent base units, such as seconds for duration and bytes for size, under the actual project naming contract. Counter names commonly end in _total; names should not encode changing label values. Avoid mixing different physical quantities under one metric name. A dashboard unit label does not convert the stored measurement automatically in every tool. If an old metric used milliseconds, document a deliberate migration rather than silently dividing one consumer while others retain the old assumption. Review the official naming guidance alongside the fixed server-version documentation.

Expose only the evidence that is needed

Metric endpoints can reveal deployment details and business activity even when they contain no obvious password. Keep unnecessary personal fields, credentials, and unbounded identifiers out of labels. Access and transport protections belong to the real environment’s authorized design. Do not make collection trigger expensive business work or mutate application state; instrumentation should expose observations with controlled cost. This course opens no listener and performs no collection. The Python model validates quantity behavior only, leaving actual library concurrency, serialization, HTTP negotiation, authentication, and scrape compatibility untested.

Common errors and fixes

A gauge decrease is interpreted as a restart

Why it happens: Counter logic was applied to a current value.
How to fix it: Choose queries from the quantity’s type and meaning.
Prevent it next time: Keep instrument semantics with the metric contract.

TYPE counter makes a wrong rate look valid

Why it happens: Metadata was treated as a correctness guarantee.
How to fix it: Review increments, resets, and observation boundaries.
Prevent it next time: Test representative event transitions.

The display changes units without a data migration

Why it happens: A label was confused with numeric conversion.
How to fix it: Align source measurement and every consumer.
Prevent it next time: Version unit changes and known-value fixtures.

Check your understanding

1. Should current free memory be modeled as an ever-increasing counter?

Show worked solution

No. It is a current quantity that can rise or fall. Choose a suitable gauge representation and define units and scope. A separate cumulative allocation counter can be useful, but it measures a different quantity and cannot replace the current-state observation.

2. A metric says completed writes but increments before storage. What should change?