Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (prometheus-query) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Welcome to 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

⚠️ This library does not export metrics. Please use prom-client instead.

For building shiny Charts, you may like this chartjs plugin: samber/chartjs-plugin-datasource-prometheus.

^{Sponsored by:}

100% OpenTelemetry-native observability platform
Simple to use, built on open standards, and designed for full cost control

🚀 Install

NodeJS

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

Browser

<script src="https://cdn.jsdelivr.net/npm/prometheus-query/dist/prometheus-query.umd.min.js"></script>

<script type="application/javacript">
    const prom = new Prometheus.PrometheusDriver(...);
</script>

💡 Quick start

import { PrometheusDriver } from 'prometheus-query';

const prom = new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    baseURL: "/api/v1" // default value
});

Instant query

// 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:

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

// 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:

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

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:

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

prom.alerts()
    .then(console.log)
    .catch(console.error);

Output:

[
  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:

new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    auth: {
        username: 'foo',
        password: 'bar'
    }
});

Using cookies:

new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    withCredentials: true
});

Proxy

new PrometheusDriver({
    endpoint: "https://prometheus.demo.do.prometheus.io",
    proxy: {
        host: 'proxy.acme.com',
        port: 8080
    }
});

Hook HTTP requests and responses

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

Author

👤 Samuel Berthe

Twitter: @samuelberthe
Github: @samber

💫 Show your support

Give a ⭐️ if this project helped you!

📝 License

This project is MIT licensed.