{"id":13588539,"url":"https://github.com/prometheus/promlens","last_synced_at":"2025-04-08T06:32:13.692Z","repository":{"id":62408396,"uuid":"547991185","full_name":"prometheus/promlens","owner":"prometheus","description":"PromLens – The query builder, analyzer, and explainer for PromQL","archived":false,"fork":false,"pushed_at":"2025-03-10T08:49:42.000Z","size":3116,"stargazers_count":614,"open_issues_count":33,"forks_count":39,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-10T09:42:23.166Z","etag":null,"topics":["prometheus","promlens","promql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prometheus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-08T18:03:24.000Z","updated_at":"2025-03-10T08:48:20.000Z","dependencies_parsed_at":"2024-01-14T10:16:58.998Z","dependency_job_id":"c21411e3-6d90-404f-a519-aa017c16cff9","html_url":"https://github.com/prometheus/promlens","commit_stats":{"total_commits":63,"total_committers":11,"mean_commits":"5.7272727272727275","dds":0.7619047619047619,"last_synced_commit":"4465da0cc52038137deb69a22e20fd98a6a9ed23"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpromlens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpromlens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpromlens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fpromlens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prometheus","download_url":"https://codeload.github.com/prometheus/promlens/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247792091,"owners_count":20996877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["prometheus","promlens","promql"],"created_at":"2024-08-01T15:06:46.830Z","updated_at":"2025-04-08T06:32:10.798Z","avatar_url":"https://github.com/prometheus.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","others"],"sub_categories":[],"readme":"# PromLens\n\nPromLens is a web-based PromQL query builder, analyzer, and visualizer.\n\nPromLens was initially created as a commercial software by [PromLabs](https://promlabs.com/) and then donated to the open-source Prometheus project by PromLabs and [Chronosphere](https://www.chronosphere.io/).\n\n## Reporting issues\n\nPlease file issues on the [GitHub issue tracker](https://github.com/prometheus/promlens/issues).\n\n## Installing PromLens\n\nThere are multiple ways of installing PromLens:\n\n### Using pre-built release binaries\n\nYou can find pre-built release binaries for PromLens on the [GitHub releases page](https://github.com/prometheus/promlens/releases).\n\n### Using Docker\n\nDocker images are available on [Docker Hub](https://hub.docker.com/r/prom/promlens) and [Quay](https://quay.io/repository/prometheus/promlens).\n\nAs a minimal example, you should be able to run PromLens like this:\n\n```\ndocker run -p 8080:8080 prom/promlens\n```\n\n### Building from source\n\nTo build PromLens from source, you need:\n\n* Go [version 1.17 or greater](https://golang.org/doc/install).\n* NodeJS [version 16 or greater](https://nodejs.org/).\n  * 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](https://stackoverflow.com/a/69699772)).\n* npm [version 7 or greater](https://www.npmjs.com/).\n\n_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._\n\nStart by cloning the repository:\n\n```bash\ngit clone https://github.com/prometheus/promlens.git\ncd promlens\n```\n\nBuild PromLens:\n\n```bash\nmake build\n```\n\nThis builds the React-based web UI and compiles it into a Go binary that serves it.\n\nNow you can run PromLens like this:\n\n```bash\n./promlens\n```\n\n## Running PromLens\n\nThe following documents how to run PromLens with various options and features.\n\n### Example deployment\n\nLet's start with a minimal and a more elaborate example first.\n\nTo run PromLens without any advanced features (link sharing, Grafana integration, etc.) enabled:\n\n```\n./promlens\n```\n\nThis starts PromLens on http://localhost:8080/ (you can override this using the `--web.listen-address` flag).\n\nTo 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):\n\n```\n./promlens \\\n  --shared-links.sql.driver=sqlite \\\n  --shared-links.sql.dsn=/tmp/promlens-links.db \\\n  --grafana.url=$GRAFANA_URL \\\n  --grafana.api-token=$GRAFANA_API_TOKEN\n```\n\n### Command-line flags\n\nTo see all available command-line flags, run:\n\n```\n./promlens --help\n```\n\nFor boolean flags that default to `true`, you can set them to `false` by specifying `--no-\u003cflag-name\u003e`, e.g. `--no-shared-links.sql.create-tables`.\n\n### Enabling link sharing\n\nLink sharing allows persisting the state of an entire PromLens query page and sharing it with others.\n\nBy default, the link sharing backend is disabled. You can enable link sharing either via Google Cloud Storage, MySQL, or SQLite:\n\n#### Google Cloud Storage\n\nTo use Google Cloud Storage (GCS) for link sharing, set the `--shared-links.gcs.bucket=\u003cbucket name\u003e` 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).\n\n#### SQLite\n\nTo save shared links to a local SQLite database, set the `--shared-links.sql.driver=sqlite` and `--shared-links.sql.dsn=\u003cdatabase filename\u003e` flags.\n\n#### MySQL\n\nTo save shared links in a MySQL database, set the `--shared-links.sql.driver=mysql` and `--shared-links.sql.dsn=\u003cdata source name\u003e` flag (see https://github.com/go-sql-driver/mysql#dsn-data-source-name for MySQL DSN specifications).\n\nBy 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:\n\n```sql\nCREATE TABLE IF NOT EXISTS link (\n  id INT AUTO_INCREMENT PRIMARY KEY,\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n  short_name VARCHAR(11) UNIQUE,\n  page_state TEXT\n);\n\nCREATE TABLE IF NOT EXISTS view(\n  id INT AUTO_INCREMENT PRIMARY KEY,\n  link_id INTEGER,\n  viewed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n  FOREIGN KEY(link_id) REFERENCES link(id)\n);\n```\n\n#### Postgres\n\nTo save shared links in a Postgres database, set the `--shared-links.sql.driver=postgres` and `--shared-links.sql.dsn=\u003cdata source name\u003e` flag (see https://pkg.go.dev/github.com/lib/pq#hdr-Connection_String_Parameters for Postgres DSN specifications).\n\nBy 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:\n\n```sql\nCREATE TABLE IF NOT EXISTS link (\n  id SERIAL PRIMARY KEY,\n  created_at timestamptz DEFAULT now(),\n  short_name VARCHAR(11) UNIQUE,\n  page_state TEXT\n);\n\nCREATE TABLE IF NOT EXISTS view(\n  id SERIAL PRIMARY KEY,\n  link_id INTEGER,\n  viewed_at timestamptz DEFAULT now(),\n  FOREIGN KEY(link_id) REFERENCES link(id)\n);\n```\n\n### Enabling Grafana datasource integration\n\nTo 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).\n\n#### Creating a Grafana API token\n\nTo create an API token suitable for looking up datasources in Grafana:\n\n- Head to \"Configuration \u003e API Keys\" in Grafana.\n- Click \"Add API key\".\n- 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).\n- Press \"Add\" and note down the displayed API key.\n\n### Set Grafana datasource in URL\n\nYou 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 `\u003cPromLenURL\u003e/api/page_config`.\n\n### Direct links to queries\n\nYou 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.\n\n## Architecture\n\nDepending on whether you use advanced features, the PromLens backend has fewer or more responsibilities:\n\n### Basic features\n\nWhen 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:\n\n![Basic PromLens architecture](docs/images/promlens_basic_architecture.svg)\n\n### Advanced features\n\nIf 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:\n\n![Advanced PromLens architecture](docs/images/promlens_advanced_architecture.svg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fpromlens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprometheus%2Fpromlens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fpromlens/lists"}