PromQL Basics

Introduction Key Concepts Syntax Examples Best Practices FAQ

1. Introduction

PromQL (Prometheus Query Language) is a powerful query language designed for Prometheus, an open-source monitoring and alerting toolkit. It allows users to select and aggregate time series data in real-time.

Key Takeaway: PromQL is essential for querying metrics stored in Prometheus efficiently.

2. Key Concepts

**Metric**: A key-value pair representing a measurement.
**Time series**: A stream of data points indexed by time.
**Labels**: Key-value pairs that differentiate time series.
**Selector**: A way to filter time series based on labels.

3. Syntax

PromQL has a specific syntax for querying metrics. Here’s a basic structure:

metric_name{label_name="value"}

The above syntax retrieves all time series for the specified metric with the matching label.

Tip: Use curly braces to filter based on labels.

4. Examples

4.1 Basic Query

http_requests_total{job="api"}

This query fetches the total number of HTTP requests for the "api" job.

4.2 Aggregation

sum(http_requests_total{job="api"}) by (status)

This aggregates total HTTP requests by their status code.

4.3 Rate Calculation

rate(http_requests_total[5m])

Calculates the rate of HTTP requests over the last 5 minutes.

5. Best Practices

Use precise label names for clarity.
Limit the use of wildcards in selectors to improve performance.
Regularly review and refactor queries for efficiency.
Utilize aggregation functions to summarize data effectively.

6. FAQ

What is a metric in PromQL?

A metric is a fundamental concept in Prometheus, representing a specific measurement over time. It is identified by its name and associated labels.

How do I filter metrics by labels?

You can filter metrics by labels using curly braces. For example: metric_name{label="value"}.

What are aggregation functions?

Aggregation functions in PromQL allow you to combine multiple time series into a single time series. Examples include sum, avg, and max.

7. Flowchart for Querying Process


graph TD;
    A[Start] --> B{Select Metric};
    B -->|Yes| C[Apply Filters];
    B -->|No| D[No Metric Found];
    C --> E{Aggregation Needed?};
    E -->|Yes| F[Apply Aggregation];
    E -->|No| G[Retrieve Data];
    F --> G;
    G --> H[End];