https://github.com/samber/prometheus-query-js
📊 A Javascript client for Prometheus query API
https://github.com/samber/prometheus-query-js
admin api client javascript label metrics prometheus query series timeseries tsdb
Last synced: 21 days ago
JSON representation
📊 A Javascript client for Prometheus query API
- Host: GitHub
- URL: https://github.com/samber/prometheus-query-js
- Owner: samber
- License: mit
- Created: 2020-02-09T19:05:15.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-11-11T16:33:55.000Z (6 months ago)
- Last Synced: 2025-04-11T14:23:21.867Z (23 days ago)
- Topics: admin, api, client, javascript, label, metrics, prometheus, query, series, timeseries, tsdb
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/prometheus-query
- Size: 798 KB
- Stars: 64
- Watchers: 6
- Forks: 17
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Welcome to prometheus-query 👋
[](https://npmjs.org/package/prometheus-query)
[](#)
> A Javascript client for Prometheus **query** API.
## ✨ Features
- Thin & **minimal low-level HTTP client** to interact with Prometheus's API
- Works both on the **browser** and **node.js**
- **UMD compatible**, you can use it with any module loader
- Supports **query** and admin [APIs](https://prometheus.io/docs/prometheus/latest/querying/api/)
⚠️ This library does not export metrics. Please use [prom-client](https://github.com/siimon/prom-client) instead.
For building shiny Charts, you may like this chartjs plugin: [samber/chartjs-plugin-datasource-prometheus](https://github.com/samber/chartjs-plugin-datasource-prometheus).
Sponsored by:
Cloud-native search engine for observability - An OSS alternative to Splunk, Elasticsearch, Loki, and Tempo.
## 🚀 Install
### NodeJS
```sh
npm install prometheus-query
```
### Upgrade from v2 to v3
- `prometheus-query-js` has been recoded into Typescript.
- Type definitions.
- API update:
- `PrometheusQuery` is not the default export anymore.
- `PrometheusQuery` has been renamed as `PrometheusDriver`.
- [See examples](./examples/nodejs/app.ts)
### Browser
```html
const prom = new Prometheus.PrometheusDriver(...);
```
## 💡 Quick start
```js
import { PrometheusDriver } from 'prometheus-query';
const prom = new PrometheusDriver({
endpoint: "https://prometheus.demo.do.prometheus.io",
baseURL: "/api/v1" // default value
});
```
### Instant query
```js
// last `up` value
const q = 'up{instance="demo.do.prometheus.io:9090",job="node"}';
prom.instantQuery(q)
.then((res) => {
const series = res.result;
series.forEach((serie) => {
console.log("Serie:", serie.metric.toString());
console.log("Time:", serie.value.time);
console.log("Value:", serie.value.value);
});
})
.catch(console.error);
```
Output:
```txt
Serie: up{instance="prometheus.demo.do.prometheus.io:9100", job="node"}
Time: Sun Feb 16 2020 18:33:59 GMT+0100 (Central European Standard Time)
Value: 1
```
### Range query
```js
// up during past 24h
const q = 'up';
const start = new Date().getTime() - 24 * 60 * 60 * 1000;
const end = new Date();
const step = 6 * 60 * 60; // 1 point every 6 hours
prom.rangeQuery(q, start, end, step)
.then((res) => {
const series = res.result;
series.forEach((serie) => {
console.log("Serie:", serie.metric.toString());
console.log("Values:\n" + serie.values.join('\n'));
});
})
.catch(console.error);
```
Output:
```txt
Serie: up{instance="prometheus.demo.do.prometheus.io:9090", job="prometheus"}
Values:
Sat Feb 15 2020 18:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 00:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 06:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 12:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 18:21:47 GMT+0100 (Central European Standard Time): 1
Serie: up{instance="prometheus.demo.do.prometheus.io:9093", job="alertmanager"}
Values:
Sat Feb 15 2020 18:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 00:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 06:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 12:21:47 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 18:21:47 GMT+0100 (Central European Standard Time): 1
Serie: up{instance="prometheus.demo.do.prometheus.io:9100", job="node"}
Values:
Sat Feb 15 2020 18:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 00:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 06:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 12:20:51 GMT+0100 (Central European Standard Time): 1
Sun Feb 16 2020 18:20:51 GMT+0100 (Central European Standard Time): 1
```
### List series matching query
```js
const match = 'up';
const start = new Date().getTime() - 24 * 60 * 60 * 1000;
const end = new Date();
prom.series(match, start, end)
.then((res) => {
console.log('Series:');
console.log(res.join('\n'));
})
.catch(console.error);
```
Output:
```txt
up{instance="demo.do.prometheus.io:9090", job="prometheus"}
up{instance="demo.do.prometheus.io:9093", job="alertmanager"}
up{instance="demo.do.prometheus.io:9100", job="node"}
```
### List all active alerts
```js
prom.alerts()
.then(console.log)
.catch(console.error);
```
Output:
```js
[
Alert {
activeAt: 2019-11-14T20:04:36.629Z,
annotations: {},
labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'alertmanager' },
state: 'firing',
value: 1
},
Alert {
activeAt: 2019-11-14T20:04:36.629Z,
annotations: {},
labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'node' },
state: 'firing',
value: 1
},
Alert {
activeAt: 2019-11-14T20:04:36.629Z,
annotations: {},
labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'prometheus' },
state: 'firing',
value: 1
},
Alert {
activeAt: 2019-11-14T20:04:36.629Z,
annotations: {},
labels: { alertname: 'ExampleAlertAlwaysFiring', job: 'pushgateway' },
state: 'firing',
value: 1
}
]
```
### Authenticated query
Using basic auth:
```ts
new PrometheusDriver({
endpoint: "https://prometheus.demo.do.prometheus.io",
auth: {
username: 'foo',
password: 'bar'
}
});
```
Using cookies:
```ts
new PrometheusDriver({
endpoint: "https://prometheus.demo.do.prometheus.io",
withCredentials: true
});
```
### Proxy
```ts
new PrometheusDriver({
endpoint: "https://prometheus.demo.do.prometheus.io",
proxy: {
host: 'proxy.acme.com',
port: 8080
}
});
```
### Hook HTTP requests and responses
```ts
new PrometheusDriver({
endpoint: "https://prometheus.demo.do.prometheus.io",
proxy: {
host: 'proxy.acme.com',
port: 8080
},
requestInterceptor: {
onFulfilled: (config: AxiosRequestConfig) => {
return config;
},
onRejected: (error: any) => {
return Promise.reject(error.message);
}
},
responseInterceptor: {
onFulfilled: (res: AxiosResponse) => {
return res;
},
onRejected: (error: any) => {
return Promise.reject(error.message);
}
}
});
```
## 🔐 Security advisory
If you open a Prometheus instance on Internet, it would be a good idea to block some routes.
Start by blocking `/api/v1/admin`. I'm pretty sure allowing only `/api/v1/query` and `/api/v1/query_range` will match your needs.
Also don't use Prometheus as a multitenant timeseries database!
At your own risk... 😘
## 🤝 Contributing
The Prometheus Query client is open source and contributions from the community (you!) are welcome.
There are many ways to contribute: writing code, documentation, reporting issues...
[How-to](./CONTRIBUTING.md)
## Author
👤 **Samuel Berthe**
* Twitter: [@samuelberthe](https://twitter.com/samuelberthe)
* Github: [@samber](https://github.com/samber)
## 💫 Show your support
Give a ⭐️ if this project helped you!
[](https://www.patreon.com/samber)
## 📝 License
Copyright © 2020 [Samuel Berthe](https://github.com/samber).
This project is [MIT](./LICENSE) licensed.