Prometheus Data Types and Principles

1. Introduction

Prometheus is an open-source system monitoring and alerting toolkit originally developed at SoundCloud. A core component of Prometheus is its data model, which defines the different data types used to represent monitored metrics. Understanding these data types is essential for effectively using Prometheus to collect, store, and query monitoring data. This article will delve into Prometheus data types, provide Python code examples to demonstrate their usage, analyze how they change over time (within one minute and five minutes), explain the underlying change principles, and finally present a Prometheus flowchart using English bash box diagrams.

2. Prometheus Data Types

2.1 Counter

A Counter in Prometheus is a cumulative metric representing a single numerical value that only increases. It is typically used to count events such as the number of requests served, tasks completed, or errors occurred.

Python Code Example

from prometheus_client import Counter  

# Create a counter metric  
request_counter = Counter('http_requests_total', 'Total number of HTTP requests')  

# Simulate some HTTP requests  
for _ in range(10):  
    request_counter.inc()  

print(request_counter._value.get())  

Explanation:

• Import the Counter class from the prometheus_client library.
• Create a counter named http_requests_total with a help string.
• Simulate 10 HTTP requests by incrementing the counter.
• Print the current counter value.

Data Change Over Time

• One Minute:
  Suppose a web server receives 10 requests per minute. If the initial counter value is 50, it will increase to 60 after one minute.
• Five Minutes:
  At a constant rate of 10 requests per minute, the counter will increase by 50 over five minutes, reaching 100 from an initial value of 50.

Change Principle:
Counters increment by 1 each time the tracked event occurs. Prometheus stores the cumulative sum over time, and the value never decreases naturally, making it ideal for tracking long-term event trends.

2.2 Gauge

A Gauge is a metric representing a single numerical value that can increase or decrease arbitrarily. It is used for measuring values like temperature, memory usage, or concurrent connections.

Python Code Example

from prometheus_client import Gauge  

# Create a gauge metric  
memory_usage_gauge = Gauge('memory_usage_bytes', 'Memory usage in bytes')  

# Simulate memory usage changes  
memory_usage_gauge.set(1024)  
memory_usage_gauge.inc(512)  
memory_usage_gauge.dec(256)  

print(memory_usage_gauge._value.get())  

Explanation:

• Import the Gauge class and create a gauge named memory_usage_bytes.
• Set the initial value to 1024 bytes, increment by 512, and decrement by 256.
• Print the final gauge value (1280 bytes).

Data Change Over Time

• One Minute:
  Memory usage can fluctuate rapidly. For example, if the initial value is 1024 bytes and processes consume an additional 300 bytes, the gauge rises to 1324 bytes. If processes release 100 bytes, it drops to 1224 bytes.
• Five Minutes:
  Values may undergo multiple changes (e.g., 1024 → 1324 → 1200 → 1500 → 1400 → 1600 bytes over five minutes).

Change Principle:
Gauges can be explicitly set, incremented, or decremented. Prometheus records the current value at each sampling interval, reflecting the real-time state of the monitored entity.

2.3 Histogram

A Histogram samples observations (e.g., request durations or response sizes) and counts them in configurable buckets, while also providing a sum of all values.

Python Code Example

from prometheus_client import Histogram  
import random  

# Create a histogram metric with specified buckets  
request_duration_histogram = Histogram(  
    'http_request_duration_seconds',  
    'HTTP request duration in seconds',  
    buckets=(0.1, 0.2, 0.3, 0.4, 0.5)  
)  

# Simulate 20 request durations  
for _ in range(20):  
    duration = random.uniform(0, 0.6)  
    request_duration_histogram.observe(duration)  

# Print results  
print(f"Sum: {request_duration_histogram._sum.get()}")  
print(f"Count: {request_duration_histogram._count.get()}")  
for bucket, count in request_duration_histogram._buckets.items():  
    print(f"Bucket {bucket}: {count.get()}")  

Explanation:

• Define a histogram with buckets for 0.1–0.5 seconds.
• Simulate 20 request durations and record them using observe().
• Print the total sum, count, and bucket distributions.

Data Change Over Time

• One Minute:
  New observations (e.g., 25 requests in one minute) increase the count and sum, and bucket counts update based on actual durations.
• Five Minutes:
  Accumulated observations lead to larger counts and sums, with bucket distributions shifting if more long-duration requests occur.

Change Principle:
Each observation is assigned to a bucket, and the sum is updated. Histograms build data distributions over time, enabling analysis of value ranges and magnitudes.

2.4 Summary

A Summary samples observations and calculates quantiles (e.g., median, 90th percentile) to summarize data distributions, unlike histograms which use fixed buckets.

Python Code Example

from prometheus_client import Summary  

# Create a summary with labels for endpoints  
response_size_summary = Summary(  
    'http_response_size_bytes',  
    'HTTP response size in bytes',  
    labelnames=['endpoint']  
)  

# Record observations for different endpoints  
response_size_summary.labels(endpoint='/api/v1/users').observe(1024)  
response_size_summary.labels(endpoint='/api/v1/posts').observe(2048)  

# Print results  
print(f"Sum: {response_size_summary._sum.get()}")  
print(f"Count: {response_size_summary._count.get()}")  
for quantile, sum_val in response_size_summary._quantile_sum.items():  
    print(f"Quantile {quantile}: {sum_val.get()}")  

Explanation:

• Create a summary with an endpoint label to distinguish API routes.
• Record response sizes for two endpoints and print sums, counts, and quantile data.

Data Change Over Time

• One Minute:
  New requests update the count, sum, and quantiles. For example, larger responses may increase the 90th percentile value.
• Five Minutes:
  Accumulated data improves quantile accuracy, with counts and sums growing and distributions reflecting long-term trends.

Change Principle:
Observations update the running sum, count, and quantile calculations (using algorithms like moving windows). Quantiles adjust dynamically to reflect the latest data distribution.

3. Prometheus Flowchart (English Bash Box Diagrams)

+-------------------+  
| Prometheus Server |  
+-------------------+  
|                   |  
|  Data Collection  |  
|  (Pull Model)     |  
|                   |  
|  Targets         |<---+  
|  (Exporters)     |    |  
|                   |    |  
+-------------------+    |  
                        |  
+-------------------+    |  
|  Exporter         |    |  
|  (e.g., Node     |    |  
|  Exporter)       |    |  
+-------------------+    |  
                        |  
|  Metrics          |    |  
|  (Counter, Gauge, |    |  
|  Histogram,       |    |  
|  Summary)         |    |  
+-------------------+    |  
                        |  
|  Push Metrics      |<---+  
|  to Prometheus    |  
+-------------------+  
|                   |  
|  Data Storage     |  
|  (TSDB - Time -    |  
|  Series Database) |  
|                   |  
+-------------------+  
|                   |  
|  Querying        |  
|  (PromQL)        |  
|                   |  
+-------------------+  
|                   |  
|  Visualization   |  
|  (e.g., Grafana) |  
|                   |  
+-------------------+  

Flowchart Explanation:

1. Prometheus Server pulls metrics from targets (exporters) using a pull-based model.
2. Exporters (e.g., Node Exporter) collect metrics from systems and expose them in Prometheus-compatible formats.
3. Metrics (Counters, Gauges, Histograms, Summaries) are pushed to the Prometheus Server.
4. The server stores metrics in its Time-Series Database (TSDB).
5. Users query metrics using PromQL.
6. Queried data is visualized via tools like Grafana.

4. Conclusion

Understanding Prometheus data types is critical for effective system monitoring:

• Counters track cumulative events.
• Gauges monitor fluctuating values.
• Histograms analyze data distributions in buckets.
• Summaries provide quantile-based insights.

Python examples illustrate implementation and temporal changes, while the flowchart outlines Prometheus’ data flow from collection to visualization. With this knowledge, users can leverage Prometheus to efficiently monitor and manage their systems.

Leapcell: The Best of Serverless Web Hosting

Leapcell is the ideal platform for deploying Python services.

🚀 Build with Your Favorite Language

Develop effortlessly in JavaScript, Python, Go, or Rust.

🌍 Deploy Unlimited Projects for Free

Only pay for resource usage—no requests, no charges.

⚡ Pay-as-You-Go, No Hidden Costs

No idle fees, just seamless scalability.

📖 Explore Our Documentation
🔹 Follow us on Twitter: @LeapcellHQ