prometheus-api
Extended HTTP API service for Prometheus
Table of Contents
About The Project
This project enhances the native Prometheus HTTP API by providing additional features and addressing its limitations. Running as a sidecar alongside the Prometheus server enables users to extend the capabilities of the API.
One notable limitation of the native Prometheus HTTP API is the inability to programmatically create/delete rules. This project addresses this limitation by offering a solution for rule creation/deletion via the API. By leveraging prometheus-api, users can overcome the native constraints, gaining the ability to create rules programmatically. This enhances flexibility and automation in monitoring and alerting workflows.
ⓘ The decision to exclude a rule creation feature in the Prometheus API, as discussed in this GitHub issue, prioritizes stability and integrity within the Prometheus ecosystem. prometheus-api serves as an external solution, seamlessly integrating with existing Prometheus deployments while providing the sought-after rule-creation capability.
Architecture Overview
Getting Started
Prerequisites
The following prerequisites are required to get up and running with this tool:
- The Prometheus server's rules directory must be shared and accessible
- The Prometheus lifecycle API must be enabled to allow requesting the /reload API
Quick Start
Get prometheus-api up and running in minutes.
In this quick-start guide, you will run Prometheus and prometheus-api services using Docker Compose and send requests to
the API service. Please refer to this example
guide to get started.
Examples
A simple example of recording rules created using an API would be:
Request
curl -i -XPUT 'http://localhost:5000/api/v1/rules/example-record.yml' \
--header 'Content-Type: application/json' \
--data '{
"data": {
"groups": [
{
"name": "ExampleRecordingRule",
"rules": [
{
"record": "code:prometheus_http_requests_total:sum",
"expr": "sum by (code) (prometheus_http_requests_total)"
}
]
}
]
}
}'Response
HTTP/1.1 201 Created
content-length: 66
content-type: application/json
{"status":"success","message":"The rule was created successfully"}
API Model
The prometheus-api, built upon REST API design principles, provides a seamless and efficient way to interact with native Prometheus HTTP API. If you would like to explore its capabilities and learn more about its endpoints, request formats, and response structures, please refer to the comprehensive documentation available here.
Configuration
Flags
usage: python3 main.py [option]
Extended HTTP API service for Prometheus
optional arguments:
-h, --help show this help message and exit
--web.listen-address WEB.LISTEN_ADDRESS
address to listen on for API
--file.prefix FILE.PREFIX
a prefix of filenames generated by the server
--file.extension FILE.EXTENSION
rule files will be created with this suffix
--log.level {debug,info,warning,error}
only log messages with the given severity or above. One of: [debug, info, warning, error]
required parameters:
--rule.path RULE.PATH
path to Prometheus rules directory
--prom.addr PROM.ADDR
URL of Prometheus server, e.g. http://localhost:9090
Roadmap
- Add Prometheus instrumentation to expose metrics.
- Add a Bulk API to allow the creation of multiple rules via a single API call.
- Implement a way to update existing rules through the API.
Author and Maintainer
Hayk Davtyan:
- Email - hayko5999@gmail.com
- GitHub - hayk96
License
MIT License, see LICENSE.