mudhorn/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2025-01-12 06:17:27 -08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Add readme for lezer-promql and update codemirror-promql readme (#10875)

Browse source 
Signed-off-by: Augustin Husson <husson.augustin@gmail.com>
This commit is contained in:
Augustin Husson 2022-06-22 16:57:03 +02:00 committed by GitHub
parent 04fe2c9522
commit 87ffac3e9d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 64 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
web/ui/module/codemirror-promql/README.md
View file

@ -1,27 +1,17 @@
CodeMirror-promql 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 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/)). 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) ![preview](https://user-images.githubusercontent.com/4548045/95660829-d5e4b680-0b2a-11eb-9ecb-41dca6396273.gif)
## Where does it come from? ## Installation
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
This mode is available as a npm package: This mode is available as a npm package:
```bash ```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 **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: packages you need to install:
* **@codemirror/autocomplete** * **@codemirror/autocomplete**
* **@codemirror/highlight**
* **@codemirror/language** * **@codemirror/language**
* **@codemirror/lint** * **@codemirror/lint**
* **@codemirror/state** * **@codemirror/state**
* **@codemirror/view** * **@codemirror/view**
* **@lezer/common**
```bash ```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 **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: them, then the easiest way is this one:
```typescript ```typescript
import { PromQLExtension } from 'codemirror-promql'; import {PromQLExtension} from '@prometheus-io/codemirror-promql';
import { basicSetup } from '@codemirror/basic-setup'; import {basicSetup} from '@codemirror/basic-setup';
import { EditorState } from '@codemirror/state'; import {EditorState} from '@codemirror/state';
import { EditorView } from '@codemirror/view'; import {EditorView} from '@codemirror/view';
const promQL = new PromQLExtension() const promQL = new PromQLExtension()
new EditorView({ 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. Use it cautiously. A high value of this limit can cause a crash of your browser due to too many data fetched.
```typescript ```typescript
const promQL = new PromQLExtension().setComplete({ maxMetricsMetadata: 10000 }) const promQL = new PromQLExtension().setComplete({maxMetricsMetadata: 10000})
``` ```
#### Connect the autocompletion extension to a remote Prometheus server #### 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. parameter, the rest of the config will be ignored, and the Prometheus client won't be initialized.
```typescript ```typescript
const promQL = new PromQLExtension().setComplete({ remote: { url: 'https://prometheus.land' } }) const promQL = new PromQLExtension().setComplete({remote: {url: 'https://prometheus.land'}})
``` ```
###### Override FetchFn ###### 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. that is used to perform any required HTTP request.
```typescript ```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 ###### 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**. value is `12 * 60 * 60 * 1000` (12h). The value must be defined in **milliseconds**.
```typescript ```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 ###### Error Handling
@ -157,7 +147,7 @@ You can set up your own error handler to catch any HTTP error that can occur whe
Prometheus. Prometheus.
```typescript ```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 ###### 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. You can change it to use the HTTP method `GET` if you prefer.
```typescript ```typescript
const promQL = new PromQLExtension().setComplete({ remote: { httpMethod: 'GET' } }) const promQL = new PromQLExtension().setComplete({remote: {httpMethod: 'GET'}})
``` ```
###### Override the API Prefix ###### 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: You can override this value like this:
```typescript ```typescript
const promql = new PromQLExtension().setComplete({ remote: { apiPrefix: '/my/api/prefix' } }) const promql = new PromQLExtension().setComplete({remote: {apiPrefix: '/my/api/prefix'}})
``` ```
###### Cache ###### 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**. minutes. The value must be defined in **milliseconds**.
```typescript ```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 ###### Initial Metric List
@ -226,7 +217,7 @@ interface [PrometheusClient](https://github.com/prometheus/codemirror-promql/blo
. .
```typescript ```typescript
const promQL = new PromQLExtension().setComplete({ remote: { prometheusClient: MyPrometheusClient } }) const promQL = new PromQLExtension().setComplete({remote: {prometheusClient: MyPrometheusClient}})
``` ```
#### Provide your own implementation of the autocompletion #### 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: In case you would like to provide you own implementation of the autocompletion, you can simply do it like that:
```typescript ```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. 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 ## 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.

43
web/ui/module/lezer-promql/README.md Normal file
View file

@ -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.