prometheus / promlens

PromLens – The query builder, analyzer, and explainer for PromQL

PromLens

PromLens is a web-based PromQL query builder, analyzer, and visualizer.

PromLens was initially created as a commercial software by PromLabs and then donated to the open-source Prometheus project by PromLabs and Chronosphere.

Reporting issues

Please file issues on the GitHub issue tracker.

Installing PromLens

There are multiple ways of installing PromLens:

Using pre-built release binaries

You can find pre-built release binaries for PromLens on the GitHub releases page.

Using Docker

Docker images are available on Docker Hub and Quay.

As a minimal example, you should be able to run PromLens like this:

docker run -p 8080:8080 prom/promlens

Building from source

To build PromLens from source, you need:

• Go version 1.17 or greater.
• NodeJS version 16 or greater.
  • Note: With NodeJS v17+ you may experience an error:0308010C:digital envelope routines::unsupported error. This can be worked around by either exporting the following environment variable NODE_OPTIONS=--openssl-legacy-provider (please be aware of security considerations) or downgrading to NodeJS v16 (source).
• npm version 7 or greater.

Note: This is a non-exhaustive list of dependancies, as it is assumed some standard Unix tools are available on your system. Please review build error messages for more information on missing tools.

Start by cloning the repository:

git clone https://github.com/prometheus/promlens.git
cd promlens

Build PromLens:

make build

This builds the React-based web UI and compiles it into a Go binary that serves it.

Now you can run PromLens like this:

./promlens

Running PromLens

The following documents how to run PromLens with various options and features.

Example deployment

Let's start with a minimal and a more elaborate example first.

To run PromLens without any advanced features (link sharing, Grafana integration, etc.) enabled:

./promlens

This starts PromLens on http://localhost:8080/ (you can override this using the --web.listen-address flag).

To run PromLens with link sharing and Grafana integration enabled, using SQLite for link sharing (note that you will need to provide the $GRAFANA_URL and $GRAFANA_API_KEY environment variables for this to work):

./promlens \
  --shared-links.sql.driver=sqlite \
  --shared-links.sql.dsn=/tmp/promlens-links.db \
  --grafana.url=$GRAFANA_URL \
  --grafana.api-token=$GRAFANA_API_TOKEN

Command-line flags

To see all available command-line flags, run:

./promlens --help

For boolean flags that default to true, you can set them to false by specifying --no-<flag-name>, e.g. --no-shared-links.sql.create-tables.

Enabling link sharing

Link sharing allows persisting the state of an entire PromLens query page and sharing it with others.

By default, the link sharing backend is disabled. You can enable link sharing either via Google Cloud Storage, MySQL, or SQLite:

Google Cloud Storage

To use Google Cloud Storage (GCS) for link sharing, set the --shared-links.gcs.bucket=<bucket name> flag and set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to a JSON file containing your service account credentials (needs to have permission to create, delete, and view objects in the provided bucket).

SQLite

To save shared links to a local SQLite database, set the --shared-links.sql.driver=sqlite and --shared-links.sql.dsn=<database filename> flags.

MySQL

To save shared links in a MySQL database, set the --shared-links.sql.driver=mysql and --shared-links.sql.dsn=<data source name> flag (see https://github.com/go-sql-driver/mysql#dsn-data-source-name for MySQL DSN specifications).

By default, PromLens will try to auto-create the necessary tables in your MySQL database. This requires the PromLens database user to have CREATE permissions. To turn off automatic table creation for MySQL, set the --no-shared-links.sql.create-tables flag. If you want to create tables manually, run the following against your PromLens MySQL database:

CREATE TABLE IF NOT EXISTS link (
  id INT AUTO_INCREMENT PRIMARY KEY,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  short_name VARCHAR(11) UNIQUE,
  page_state TEXT
);

CREATE TABLE IF NOT EXISTS view(
  id INT AUTO_INCREMENT PRIMARY KEY,
  link_id INTEGER,
  viewed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY(link_id) REFERENCES link(id)
);

Postgres

To save shared links in a Postgres database, set the --shared-links.sql.driver=postgres and --shared-links.sql.dsn=<data source name> flag (see https://pkg.go.dev/github.com/lib/pq#hdr-Connection_String_Parameters for Postgres DSN specifications).

By default, PromLens will try to auto-create the necessary tables in your Postgres database. This requires the PromLens database user to have CREATE permissions. To turn off automatic table creation for Postgres, set the --no-shared-links.sql.create-tables flag. If you want to create tables manually, run the following against your PromLens Postgres database:

CREATE TABLE IF NOT EXISTS link (
  id SERIAL PRIMARY KEY,
  created_at timestamptz DEFAULT now(),
  short_name VARCHAR(11) UNIQUE,
  page_state TEXT
);

CREATE TABLE IF NOT EXISTS view(
  id SERIAL PRIMARY KEY,
  link_id INTEGER,
  viewed_at timestamptz DEFAULT now(),
  FOREIGN KEY(link_id) REFERENCES link(id)
);

Enabling Grafana datasource integration

To enable selection of datasources from an existing Grafana installation, set the --grafana.url flag to the URL of your Grafana installation, as well as either the --grafana.api-token flag (providing an API token directly as a flag) or the --grafana.api-token-file flag (providing an API token from a file).

Creating a Grafana API token

To create an API token suitable for looking up datasources in Grafana:

• Head to "Configuration > API Keys" in Grafana.
• Click "Add API key".
• Give the key a descriptive name, set the "Role" to "Admin", and set its life time to the desired duration (long is recommended, as you will need to regenerate it frequently otherwise).
• Press "Add" and note down the displayed API key.

Set Grafana datasource in URL

You can pre-select a specific Grafana datasource when the page loads by appending a ds query parameter to the PromLens URL. For example, https://promlens.com/?ds=1. This works along with the q query parameter and shared links. You can find the IDs of the datasources by visiting <PromLenURL>/api/page_config.

Direct links to queries

You can link to a specific query without creating a persisted shared link by appending a q query parameter to the PromLens URL. For example, https://promlens.com/?q=up directly displays and executes the query up. For more complex shared pages, we still recommend creating a full shared page link, as this allows more control over the tree view state, as well as the selected visualization methods.

Architecture

Depending on whether you use advanced features, the PromLens backend has fewer or more responsibilities:

Basic features

When running the PromLens without any link sharing or Grafana integration, the backend is only used to serve static assets and parse PromQL queries into a tree view:

Advanced features

If you enable link sharing and/or Grafana datasource integration, the backend also stores and retrieves shared links and connects to Grafana to list datasources and proxy queries:

promlens's Issues

SQLite3 usage with CGO_ENABLE build flag error

Summary

Attempting to use the SQLite3 database backend for sharing links fails because the binary was not complied with CGO_ENABLED=1.

Goal

The project advertises the ability to use SQLite3 as a backend for the link sharing functionality.

Expected Outcome

When the binary or docker container is ran with the following parameters, the sharable links will be stored in an SQLite3 database in the given location: --shared-links.sql.driver="sqlite3" --shared-links.sql.dsn="/PATH".

Actual Outcome

The program throws the following error and fails to run: caller=main.go:191 level=error msg="Error initializing link sharer." err="error creating SQL link sharer: error enabling foreign key support: Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub"

Reproduction

The below demonstrates a method of reproducing this issue, using both the official standalone binary and the Docker container.

Standalone Binary (downloaded from GitHub release)

~/promlens-0.1.0.linux-amd64$ sha256sum promlens
f2c9a5ae428aa0a3a7097b8422b946a0289cb09bf2cebe952af4cfb78f6463ae  promlens
~/promlens-0.1.0.linux-amd64$ file promlens
promlens: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, Go BuildID=K5nNTk_EsJ11Qmo3OmoO/Z9WIbgyQRzHs5Bzv3Nbq/vrkUmd1oyhisKw0i8n6c/OsFH0xvAPR6Nx3LVqG4n, with debug_info, not stripped
~/promlens-0.1.0.linux-amd64$ ./promlens --shared-links.sql.driver="sqlite3" --shared-links.sql.dsn="~"
caller=main.go:191 level=error msg="Error initializing link sharer." err="error creating SQL link sharer: error enabling foreign key support: Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub"

Docker Container

$ docker run --rm prom/promlens --shared-links.sql.driver="sqlite3" --shared-links.sql.dsn="/tmp/promlens-links.db"
caller=main.go:191 level=error msg="Error initializing link sharer." err="error creating SQL link sharer: error enabling foreign key support: Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub"

Additional Information



The go-sqlite3 repo contains the following text confirming the above:

go-sqlite3 is cgo package. If you want to build your app using go-sqlite3, you need gcc. However, after you have built and installed go-sqlite3 with go install github.com/mattn/go-sqlite3 (which requires gcc), you can build your app without relying on gcc in future.
Important: because this is a CGO enabled package, you are required to set the environment variable CGO_ENABLED=1 and have a gcc compile present within your path.
(https://github.com/mattn/go-sqlite3#installation)

Investigation



I have attempted to build the binary myself with the CGO_ENABLED flag set to 1 in several ways with no success.

These include setting system and Go environment variables:

# go env | grep CGO_ENABLED && env | grep CGO_ENABLED
CGO_ENABLED="1"
CGO_ENABLED=1

And updating line 198 of Makefile.common to the following: CGO_ENABLED=1 $(PROMU) build --prefix $(PREFIX) $(PROMU_BINARIES).

I have also confirmed that the build process (specifically $(PROMU) build --prefix $(PREFIX) $(PROMU_BINARIES)) had the CGO_ENABLED environment variable set to 1, by reviewing the process’ environment file, at /proc/#####/environ.

I have also confirmed that gcc is installed on the system that the above build was attempted on.

Despite all of these settings, a rebuilt binary still reports the same error.

Add a configuration to use Local Time

Prometheus Web UI provides a configuration that allows the user to use Local Time both in the Graph Controls and Graph. It will be great to have this in Promlens too.

Allow to send custom headers

Some Prometheus-like services like Cortex might require additional headers for authentication.

Maybe some additional flag can be added to set a custom header when querying prometheus

Select timeframe in graph with mouse

Hi,

great tool so far.

What I am still missing is the timeframe selection feature from the original prometheus PROMQL client where you can select a given time by just left clicking and selecting with the cursor inside the graph.

I find this very useful and it's the only reason to not only use Promlens so far.

Is the on the roadmap ?
By the way... then is the next release planned ?

Thank you.
-Christian

Have native sigv4 support to be able to use promlens directly with Amazon Managed Service for Prometheus

Why?

To simplify the signing process through AWS Signature Version 4

Current workaround

promlens users need to set up aws-sigv4-proxy

Prior art

Similar work was done in Grafana: grafana/grafana#27552

Prometheus with Basic Auth

Currently Promlens does not support if Prometheus is protected via basic auth, would be great if that could be added.

Integration with cloud monitoring systems

Is it on the product roadmap to support integration with monitoring solutions available in major Cloud Providers like AWS, GCP and Azure? The use-case is to use PromQL to explore queries

use official demo

Use https://prometheus.demo.do.prometheus.io instead of https://demo.promlabs.com

Building from source requires `gnu-tar` on macOS

Creating the npm-licenses.tar.bz2 makes use of the --transform flag, which bsdtar being shipped with macOS does not support.

find $(REACT_APP_NODE_MODULES_PATH) -iname "license*" | tar cfj $(REACT_APP_NPM_LICENSES_TARBALL) --transform 's/^/npm_licenses\//' --files-from=-

It's neat - but is it actually necessary? 🤔

Of course, can be mitigated by installing gnu-tar and preferring it in the path. Perhaps, if the transform is actually necessary, this could be added as build requirement?
I know, it says non-exhaustive list - but my hope would be to find a way around it 😉

Integrate into the Prometheus web ui

It would be awesome if PromLens could just be another tab in Prometheus and those being fully integrated.

does it support analyse victoriametrics ?

allow to configure the withCredentials field

Our service needs to use credentials: “include" to in fecth() but currently withCredentials is hardcoded to false:

promlens/app/src/pages/PromLens.tsx

Line 157 in 171530e

withCredentials: false,

Can we add a flag similar to defaultPrometheusURL to allow users to configure the withCredentials field?

Store state in share link url

Feature request

As an administrator, I want to enable link sharing without configuring a backing store.

eg, Grafana's Explore page encodes relevant state like:

https://example.com/grafana/explore?orgId=1&left=%7B%22datasource%22:%228M8oDGJVz%22,%22queries%22:%5B%7B%22refId%22:%22A%22,%22datasource%22:%7B%22type%22:%22prometheus%22,%22uid%22:%228M8oDGJVz%22%7D,%22editorMode%22:%22builder%22,%22expr%22:%22go_build_info%22,%22legendFormat%22:%22__auto%22,%22range%22:true,%22instant%22:true%7D%5D,%22range%22:%7B%22from%22:%22now-1h%22,%22to%22:%22now%22%7D%7D

Benefit

Users could simply copy/paste the URL from the browser, without using the special share link UI.
It would also make Promlens operationally simpler, without requiring additional external resources.

Background

Currently, Promlens requires a storage provider (eg postgres or sqlite) to enable the share link functionality.

Looking at https://github.com/prometheus/promlens/blob/0e62d284ab9b15ef9ba380adb795bda5d8922621/pkg/sharer/sharer.go , this happens by approximately like:

1. user clicks "share link" button in client UI
2. client sends JSON of page state to server
3. server takes JSON string and generates a hash to use as the key and stores the JSON string at key
4. server returns key to client
5. client shows link in UI e.g. https://promlens-instance/?l=<key>

If the state were serialized in the link itself, the flow would be simplied:

1. user clicks "share link" button in client UI
2. client serializes page state (eg, base64 encoded json) and appends to URL as query fragment, eg https://promlens-instance/#<state>
3. client shows UI

or further:

0. as page state changes, client serializes page state into location hash with History.replaceState
1. at any point, user can copy the URL from the browser address bar

The above examples are a sketch, I'm flexible to other implementation approaches.

Is this in line with the direction for this project? I'm happy to help implement and test or discuss further.