Swiftorial Logo
Home
Swift Lessons
Matchups
CodeSnaps
Tutorials
Career
Resources

Using Prometheus API Tutorial

Introduction

The Prometheus API provides a powerful way to query and interact with the metrics collected by Prometheus. This tutorial will guide you through the essential aspects of using the Prometheus API, including how to make queries, retrieve configuration data, and understand the returned results.

Understanding the API Endpoints

Prometheus exposes several API endpoints that allow you to query time series data and metadata. The primary endpoints are:

  • /api/v1/query: For querying the current value of metrics.
  • /api/v1/query_range: For querying the values of metrics over a specific time range.
  • /api/v1/labels: For retrieving all labels in the Prometheus instance.
  • /api/v1/series: For retrieving time series data based on label matchers.

Making a Simple Query

To make a simple query to the Prometheus API, you can use the /api/v1/query endpoint. This endpoint allows you to get the current value of a metric. Here’s how to do it:

Example: Querying a Metric

Using curl to query the up metric:

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

Expected Output:

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

Querying a Range of Data

To retrieve data over a range of time, use the /api/v1/query_range endpoint. This endpoint requires specifying a time range and resolution.

Example: Querying a Range

Using curl to query the up metric over the last 5 minutes:

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

Expected Output:

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

Retrieving Labels and Series

You can retrieve all the labels or series in your Prometheus instance using the /api/v1/labels and /api/v1/series endpoints. These endpoints are useful for understanding the available metrics.

Example: Retrieving Labels

Using curl to get all labels:

curl 'http://localhost:9090/api/v1/labels'

Expected Output:

{ "status": "success", "data": [ "__name__", "instance", "job", ... ] }

Example: Retrieving Time Series

Using curl to get time series for a specific metric:

curl -G 'http://localhost:9090/api/v1/series' --data-urlencode 'match[]=up'

Expected Output:

{ "status": "success", "data": [ { "__name__": "up", "instance": "localhost:9090", "job": "prometheus" }, ... ] }

Conclusion

The Prometheus API is a powerful tool for querying and interacting with time series data. By understanding its endpoints and how to use them, you can efficiently retrieve the metrics necessary for monitoring and alerting. Experiment with the various queries to get comfortable with the API and explore the metrics your applications are exposing.