pygments-promql

A PromQL lexer for Pygments.

This Python package provides a Pygments lexer for the Prometheus Query Language. It allows Pygments and other tools (Sphinx, Chroma, etc) to highlight PromQL queries.

Installation

Using pip

To get the latest version from pypi.org:

pip install pygments-promql

Usage

Command-line

In a terminal you can echo and pipe a query directly from stdin:

echo 'prometheus_http_requests_total{code="200"}' | pygmentize -l promql

Or use a file, for example, create the example.promql file with queries from tests/example.promql. In this case the option -l promql is not needed because the lexer will be detected based on the file extension.

Showing colorized output in a terminal:

pygmentize example.promql

To generate a PNG file:

pygmentize -f png -O "line_numbers=False,style=monokai" -o example.png example.promql

Python code

The following example:

from pygments import highlight
from pygments.formatters import HtmlFormatter
from pygments_promql import PromQLLexer

query = 'http_requests_total{handler="/api/comments"}'
print(highlight(query, PromQLLexer(), HtmlFormatter()))

Will generate this HTML output:

<div class="highlight">
    <pre>
        <span></span>
	<span class="nv">http_requests_total</span>
	<span class="p">{</span>
	<span class="nl">handler</span>
	<span class="o">=</span>
	<span class="s">&quot;/api/comments&quot;</span>
	<span class="p">}</span>
	<span class="w"></span>
    </pre>
</div>

Use HtmlFormatter(noclasses=True) to include CSS inline styles on every <span> tag.

Sphinx

In order to highlight PromQL syntax in your Sphinx documentation site you just need to add this 3 lines of Python code at the end of your site's conf.py file:

from sphinx.highlighting import lexers
from pygments_promql import PromQLLexer
lexers['promql'] = PromQLLexer()

Then you will be able to use it like this:

Here's a PromQL example:

.. code-block:: promql

	# A metric with label filtering
	go_gc_duration_seconds{instance="localhost:9090"}

Testing

If you want to test, play or contribute to this repo:

git clone https://github.com/pabluk/pygments-promql.git
cd pygments-promql/
uv sync --locked --all-extras --dev
uv run pytest -v