Introduction

Prometheus itself stores metric names, labels, values, and timestamps, but it does not invent full business documentation for every metric you scrape. To understand a metric, you usually need to look at the exporter’s /metrics output, the exporter or application documentation, and sometimes the source code that defines the metric. The best description is often the one shipped with the metric itself through the HELP line in the exposition format.

Start with the /metrics Endpoint

Every Prometheus target exposes metrics in a text format that includes optional HELP and TYPE metadata. That is often the fastest place to find a description.

Example exposition:

# HELP http_requests_total Total number of HTTP requests served.
# TYPE http_requests_total counter
http_requests_total{method="GET",status="200"} 4812

The HELP line is the human-readable description. The TYPE line tells you whether the metric is a counter, gauge, histogram, summary, or untyped series.

If you have access to the target, opening its /metrics endpoint directly is often more useful than guessing from dashboards alone.

Check the Exporter Documentation

For infrastructure metrics, the exporter’s documentation is usually the next best source. Prometheus scrapes many different systems, and each exporter defines its own metric names and meanings.

For example:

• Node Exporter documents host and kernel metrics
• cAdvisor documents container resource metrics
• application-specific exporters document service-level counters and gauges

The important point is that metric meaning lives with the component that emits the metric, not with Prometheus server itself.

Read the Instrumentation Code When the Docs Are Thin

Not every metric is documented well. In custom applications, the real description may only exist in code where the metric is registered.

Example Go instrumentation:

1var requestCounter = prometheus.NewCounterVec(
2    prometheus.CounterOpts{
3        Name: "http_requests_total",
4        Help: "Total number of HTTP requests served.",
5    },
6    []string{"method", "status"},
7)

The Help field is the source of the HELP line exposed to Prometheus. If the dashboard only shows http_requests_total, the code tells you what the authors intended it to mean.

Use Naming Conventions as a Clue, Not as Full Documentation

Prometheus metric names follow conventions that help interpretation:

• counters often end in _total
• durations are often in _seconds
• sizes are often in _bytes

These conventions are useful, but they are not enough on their own. A name such as queue_depth may still require domain knowledge to understand whether it is current backlog, historical maximum, or something else entirely.

Treat the name as a clue and the HELP text or source documentation as the actual description.

Distinguish Metric Meaning from Query Meaning

Dashboards and alert rules often use PromQL expressions such as rate(http_requests_total[5m]). That expression is not the metric itself. It is a derived time-series calculation based on the raw metric.

Raw metric:

http_requests_total

Derived query:

rate(http_requests_total[5m])

If you are trying to document a dashboard, you usually need both:

• what the raw metric means
• what the PromQL transformation does

Confusing those two leads to poor monitoring documentation.

Build Better Descriptions in Your Own Systems

If you control the instrumentation, add clear HELP text at the source. Good metric descriptions should answer:

• what is being counted or measured
• the unit, if relevant
• the scope, if it is not obvious

For example, "Current number of jobs waiting in the main processing queue" is much better than "Queue size."

Prometheus makes this easy, but teams often skip it and then wonder why dashboards are hard to interpret later.

Common Pitfalls

• Looking only at a Grafana panel name and assuming it is the official metric description.
• Forgetting that the /metrics endpoint often includes HELP text already.
• Expecting Prometheus server documentation to explain every exporter-specific metric.
• Confusing raw metrics with PromQL expressions derived from them.
• Publishing custom metrics with vague or missing help strings.

Summary

• The best first place to look for metric descriptions is the target’s /metrics endpoint.
• Exporter or application documentation is usually the authoritative explanation of metric meaning.
• When docs are sparse, the instrumentation source code often reveals the intended description.
• Metric names and suffixes help, but they are not a substitute for real documentation.
• If you emit your own metrics, write clear HELP strings so future users do not have to guess.