From 87ffac3e9d2104cd368d2e8962723d9fc3ee126f Mon Sep 17 00:00:00 2001 From: Augustin Husson Date: Wed, 22 Jun 2022 16:57:03 +0200 Subject: [PATCH] Add readme for lezer-promql and update codemirror-promql readme (#10875) Signed-off-by: Augustin Husson --- web/ui/module/codemirror-promql/README.md | 51 ++++++++++------------- web/ui/module/lezer-promql/README.md | 43 +++++++++++++++++++ 2 files changed, 64 insertions(+), 30 deletions(-) create mode 100644 web/ui/module/lezer-promql/README.md diff --git a/web/ui/module/codemirror-promql/README.md b/web/ui/module/codemirror-promql/README.md index 42ed4e2c36..6d887ab2fb 100644 --- a/web/ui/module/codemirror-promql/README.md +++ b/web/ui/module/codemirror-promql/README.md @@ -1,27 +1,17 @@ CodeMirror-promql ================= -[![CircleCI](https://circleci.com/gh/prometheus/codemirror-promql.svg?style=shield)](https://circleci.com/gh/prometheus/codemirror-promql) [![GitHub license](https://img.shields.io/badge/license-Apache-blue.svg)](./LICENSE) -[![NPM version](https://img.shields.io/npm/v/codemirror-promql.svg)](https://www.npmjs.org/package/codemirror-promql) [![codecov](https://codecov.io/gh/prometheus/codemirror-promql/branch/main/graph/badge.svg?token=rBHsyXshfl)](https://codecov.io/gh/prometheus/codemirror-promql) - -## Overview This project provides a mode for [CodeMirror Next](https://codemirror.net/6) that handles syntax highlighting, linting and autocompletion for PromQL ([Prometheus Query Language](https://prometheus.io/docs/introduction/overview/)). ![preview](https://user-images.githubusercontent.com/4548045/95660829-d5e4b680-0b2a-11eb-9ecb-41dca6396273.gif) -## Where does it come from? - -The authoritative copy of this code lives in `prometheus/prometheus` and is synced to -`prometheus/codemirror-promql` on a regular basis by a bot. Please contribute any code changes to the code -in https://github.com/prometheus/prometheus/tree/main/web/ui/module/codemirror-promql. - -### Installation +## Installation This mode is available as a npm package: ```bash -npm install --save codemirror-promql +npm install --save @prometheus-io/codemirror-promql ``` **Note:** You will have to manually install different packages that are part @@ -29,14 +19,14 @@ of [CodeMirror Next](https://codemirror.net/6), as they are a peer dependency to packages you need to install: * **@codemirror/autocomplete** -* **@codemirror/highlight** * **@codemirror/language** * **@codemirror/lint** * **@codemirror/state** * **@codemirror/view** +* **@lezer/common** ```bash -npm install --save @codemirror/autocomplete @codemirror/highlight @codemirror/language @codemirror/lint @codemirror/state @codemirror/view +npm install --save @codemirror/autocomplete @codemirror/language @codemirror/lint @codemirror/state @codemirror/view @lezer/common ``` **Note 2**: that's the minimum required to install the lib. You would probably need to install as well the dependency @@ -57,10 +47,10 @@ If you want to enjoy about the different features provided without taking too mu them, then the easiest way is this one: ```typescript -import { PromQLExtension } from 'codemirror-promql'; -import { basicSetup } from '@codemirror/basic-setup'; -import { EditorState } from '@codemirror/state'; -import { EditorView } from '@codemirror/view'; +import {PromQLExtension} from '@prometheus-io/codemirror-promql'; +import {basicSetup} from '@codemirror/basic-setup'; +import {EditorState} from '@codemirror/state'; +import {EditorView} from '@codemirror/view'; const promQL = new PromQLExtension() new EditorView({ @@ -108,7 +98,7 @@ By default, the limit is 10 000 metrics. Use it cautiously. A high value of this limit can cause a crash of your browser due to too many data fetched. ```typescript -const promQL = new PromQLExtension().setComplete({ maxMetricsMetadata: 10000 }) +const promQL = new PromQLExtension().setComplete({maxMetricsMetadata: 10000}) ``` #### Connect the autocompletion extension to a remote Prometheus server @@ -127,7 +117,7 @@ Note: this is the only mandatory parameter in case you want to use the default P parameter, the rest of the config will be ignored, and the Prometheus client won't be initialized. ```typescript -const promQL = new PromQLExtension().setComplete({ remote: { url: 'https://prometheus.land' } }) +const promQL = new PromQLExtension().setComplete({remote: {url: 'https://prometheus.land'}}) ``` ###### Override FetchFn @@ -136,7 +126,7 @@ In case your Prometheus server is protected and requires a special HTTP client, that is used to perform any required HTTP request. ```typescript -const promQL = new PromQLExtension().setComplete({ remote: { fetchFn: myHTTPClient } }) +const promQL = new PromQLExtension().setComplete({remote: {fetchFn: myHTTPClient}}) ``` ###### Duration to use for looking back when retrieving metrics / labels @@ -148,7 +138,7 @@ In case you would like to provide your own duration, you can override the variab value is `12 * 60 * 60 * 1000` (12h). The value must be defined in **milliseconds**. ```typescript -const promQL = new PromQLExtension().setComplete({ remote: { lookbackInterval: 12 * 60 * 60 * 1000 } }) +const promQL = new PromQLExtension().setComplete({remote: {lookbackInterval: 12 * 60 * 60 * 1000}}) ``` ###### Error Handling @@ -157,7 +147,7 @@ You can set up your own error handler to catch any HTTP error that can occur whe Prometheus. ```typescript -const promQL = new PromQLExtension().setComplete({ remote: { httpErrorHandler: (error: any) => console.error(error) } }) +const promQL = new PromQLExtension().setComplete({remote: {httpErrorHandler: (error: any) => console.error(error)}}) ``` ###### HTTP method used @@ -168,17 +158,18 @@ endpoints `/api/v1/labels` and `/api/v1/series`. You can change it to use the HTTP method `GET` if you prefer. ```typescript -const promQL = new PromQLExtension().setComplete({ remote: { httpMethod: 'GET' } }) +const promQL = new PromQLExtension().setComplete({remote: {httpMethod: 'GET'}}) ``` ###### Override the API Prefix -The default Prometheus Client, when building the query to get data from Prometheus, is using an API prefix which is by default `/api/v1`. +The default Prometheus Client, when building the query to get data from Prometheus, is using an API prefix which is by +default `/api/v1`. You can override this value like this: ```typescript -const promql = new PromQLExtension().setComplete({ remote: { apiPrefix: '/my/api/prefix' } }) +const promql = new PromQLExtension().setComplete({remote: {apiPrefix: '/my/api/prefix'}}) ``` ###### Cache @@ -192,7 +183,7 @@ The data are stored in the cache for a limited amount of time defined by the var minutes. The value must be defined in **milliseconds**. ```typescript -const promQL = new PromQLExtension().setComplete({ remote: { cache: { maxAge: 5 * 60 * 1000 } } }) +const promQL = new PromQLExtension().setComplete({remote: {cache: {maxAge: 5 * 60 * 1000}}}) ``` ###### Initial Metric List @@ -226,7 +217,7 @@ interface [PrometheusClient](https://github.com/prometheus/codemirror-promql/blo . ```typescript -const promQL = new PromQLExtension().setComplete({ remote: { prometheusClient: MyPrometheusClient } }) +const promQL = new PromQLExtension().setComplete({remote: {prometheusClient: MyPrometheusClient}}) ``` #### Provide your own implementation of the autocompletion @@ -234,7 +225,7 @@ const promQL = new PromQLExtension().setComplete({ remote: { prometheusClient: M In case you would like to provide you own implementation of the autocompletion, you can simply do it like that: ```typescript -const promQL = new PromQLExtension().setComplete({ completeStrategy: myCustomImpl }) +const promQL = new PromQLExtension().setComplete({completeStrategy: myCustomImpl}) ``` Note: In case this parameter is provided, then the rest of the configuration is ignored. @@ -246,4 +237,4 @@ Note: In case this parameter is provided, then the rest of the configuration is ## License -Apache License 2.0, see [LICENSE](https://github.com/prometheus/codemirror-promql/blob/main/LICENSE). +The code is licensed under an [Apache 2.0](https://github.com/prometheus/prometheus/blob/main/LICENSE) license. diff --git a/web/ui/module/lezer-promql/README.md b/web/ui/module/lezer-promql/README.md new file mode 100644 index 0000000000..4cfedb4286 --- /dev/null +++ b/web/ui/module/lezer-promql/README.md @@ -0,0 +1,43 @@ +# lezer-promql + +## Overview + +This is a PromQL grammar for the [lezer](https://lezer.codemirror.net/) parser system. It is inspired by the initial +grammar coming from [Prometheus](https://github.com/prometheus/prometheus/blob/main/promql/parser/generated_parser.y) +written in yacc. + +This library is stable but doesn't provide any guideline of how to use it as it has been integrated +into [codemirror-promql](https://github.com/prometheus/prometheus/blob/main/web/ui/module/codemirror-promql). If you +want to use this library, you perhaps want to actually use **@prometheus-io/codemirror-promql** instead. + +**Note**: This library is a lezer-based implementation of the [authoritative, goyacc-based PromQL grammar](https://github.com/prometheus/prometheus/blob/main/promql/parser/generated_parser.y). +Any changes to the authoritative grammar need to be reflected in this package as well. + +## Installation + +This package is available as an npm package: + +```bash +npm install --save @prometheus-io/lezer-promql +``` + +**Note**: you will have to manually install the `lezer` dependencies as it is a peer dependency to this package. + +```bash +npm install --save @lezer/lr @lezer/highlight +``` + +## Development + +### Building + + npm i + npm run build + +### Testing + + npm run test + +## License + +The code is licensed under an [Apache 2.0](https://github.com/prometheus/prometheus/blob/main/LICENSE) license.