Prometheus Data Model

Metric Types

Prometheus supports four core metric types, each designed for a different measurement pattern. Choosing the right type is critical for accurate queries and efficient storage.

Labels and Time Series

A time series in Prometheus is uniquely identified by a metric name and a set of label name-value pairs. Each unique combination of name and labels defines a distinct time series with its own stream of samples.

http_requests_total{method="GET", endpoint="/api/v1/users", status="200"}
http_requests_total{method="POST", endpoint="/api/v1/users", status="201"}
http_requests_total{method="GET", endpoint="/api/v1/users", status="500"}

Each line above is a separate time series. The labels method, endpoint, and status create distinct dimensions. Prometheus stores each series independently, so label cardinality directly affects memory and storage.

Naming Conventions

Prometheus metric names follow strict conventions. The name must include a unit suffix and represent a single measurement type. Following these conventions ensures consistency across teams.

# Counter — total suffix
http_requests_total
disk_reads_total

# Gauge — no suffix or descriptive
heap_size_bytes
cpu_usage_ratio

# Histogram — _seconds, _bytes, etc.
http_request_duration_seconds_bucket
http_request_duration_seconds_sum
http_request_duration_seconds_count

Scrape Timestamps

When Prometheus scrapes a target, it records the timestamp of the scrape. By default, Prometheus uses the scrape time as the sample timestamp. You can also enable honor_timestamps to use the target's own timestamps.

scrape_configs:
  - job_name: "my-app"
    honor_timestamps: true
    scrape_interval: 15s
    static_configs:
      - targets: ["localhost:9090"]

When honor_timestamps is false (the default), Prometheus replaces the target's timestamp with the time it performed the scrape. This is safer when targets produce stale or incorrect timestamps.

Staleness Markers

Prometheus inserts staleness markers when a previously available series disappears from a scrape. This prevents graphs from showing old data as if it were current. Staleness markers are special NaN values appended after the last sample.

A series becomes stale when its target goes down or stops reporting. The staleness marker is inserted one scrape interval after the last successful scrape. This allows PromQL to correctly handle disappearing series in range queries.