Introduction To Prometheus Api

What is Prometheus?

Prometheus is an open-source monitoring system and time-series database that is designed for reliability and scalability. It collects metrics from configured targets at specified intervals, evaluates rule expressions, and can trigger alerts based on those rules. Prometheus is particularly well-suited for monitoring dynamic cloud-native applications and microservices.

Understanding the Prometheus API

The Prometheus API provides a way to interact with the Prometheus server. It allows users to query metrics, retrieve metadata, and perform administrative tasks. The API is a powerful tool for developers and system administrators, enabling them to access metrics programmatically and integrate them into their applications or monitoring dashboards.

API Endpoints

The Prometheus API consists of several endpoints that can be accessed via HTTP. The main endpoints include:

/api/v1/query: Executes a PromQL query at a specified time.
/api/v1/query_range: Executes a PromQL query over a range of time.
/api/v1/label//values: Retrieves all unique values for a specified label.
/api/v1/metrics: Retrieves a list of all metrics.

Making a Query

To perform a query, you can use the /api/v1/query endpoint. For example, you can retrieve the current value of a metric using the following command:

Example: Querying the up metric

curl -G 'http://localhost:9090/api/v1/query' --data-urlencode 'query=up'

{ "status": "success", "data": { "resultType": "vector", "result": [ { "metric": { "__name__": "up", "instance": "localhost:9090", "job": "prometheus" }, "value": [, "1"] } ] } }

Querying a Range of Metrics

To retrieve metrics over a specific time range, use the /api/v1/query_range endpoint. Here's how to get the values of the http_requests_total metric over the last hour:

Example: Querying a range

curl -G 'http://localhost:9090/api/v1/query_range' --data-urlencode 'query=http_requests_total' --data-urlencode 'start=' --data-urlencode 'end=' --data-urlencode 'step=15'

{ "status": "success", "data": { "resultType": "matrix", "result": [ { "metric": { "__name__": "http_requests_total", "instance": "localhost:9090", "job": "api" }, "values": [ [, "5"], [, "10"], ... ] } ] } }

Using Labels in Queries

Labels are a powerful feature in Prometheus that allow you to filter metrics. For example, if you want to get the number of HTTP requests for a specific job, you can use a label selector:

Example: Querying with labels

curl -G 'http://localhost:9090/api/v1/query' --data-urlencode 'query=http_requests_total{job="api"}'

{ "status": "success", "data": { "resultType": "vector", "result": [ { "metric": { "__name__": "http_requests_total", "job": "api", "instance": "localhost:9090" }, "value": [, "20"] } ] } }

Conclusion

The Prometheus API is a powerful interface for accessing and querying metrics in real-time. By using the various endpoints, you can retrieve metric data, perform complex queries, and integrate monitoring capabilities into your applications. Understanding how to effectively use the API is crucial for leveraging the full potential of Prometheus for monitoring your systems.