Prometheus

Litestar includes optional Prometheus exporter that is exported from litestar.contrib.prometheus. To use this package, you should first install the required dependencies:

as separate package

pip install prometheus-client

as a Litestar extra

pip install litestar[prometheus]

Once these requirements are satisfied, you can instrument your Litestar application:

Using the Prometheus Exporter

from litestar import Litestar
from litestar.contrib.prometheus import PrometheusConfig, PrometheusController

# Default app name and prefix is litestar.
prometheus_config = PrometheusConfig()


# By default the metrics are available in prometheus format and the path is set to '/metrics'.
# If you want to change the path and format you can do it by subclassing the PrometheusController class.

# Creating the litestar app instance with our custom PrometheusConfig and PrometheusController.
app = Litestar(route_handlers=[PrometheusController], middleware=[prometheus_config.middleware])

You can also customize the configuration:

Python 3.8+

Configuring the Prometheus Exporter

from typing import Any, Dict

from litestar import Litestar, Request
from litestar.contrib.prometheus import PrometheusConfig, PrometheusController


# We can modify the path of our custom handler and override the metrics format by subclassing the PrometheusController.
class CustomPrometheusController(PrometheusController):
    path = "/custom-path"
    openmetrics_format = True


# Let's assume this as our extra custom labels which we want our metrics to have.
# The values can be either a string or a callable that returns a string.
def custom_label_callable(request: Request[Any, Any, Any]) -> str:
    return "v2.0"


extra_labels = {
    "version_no": custom_label_callable,
    "location": "earth",
}

# Customizing the buckets for the histogram.
buckets = [0.1, 0.2, 0.3, 0.4, 0.5]


# Adding exemplars to the metrics.
# Note that this supported only in openmetrics format.
def custom_exemplar(request: Request[Any, Any, Any]) -> Dict[str, str]:
    return {"trace_id": "1234"}


# Creating the instance of PrometheusConfig with our own custom options.
# The givenn options ara not necessary, you can use the default ones
# as well by just creating a raw instance PrometheusConfig()
prometheus_config = PrometheusConfig(
    app_name="litestar-example",
    prefix="litestar",
    labels=extra_labels,
    buckets=buckets,
    exemplars=custom_exemplar,
    excluded_http_methods=["POST"],
)


# Creating the litestar app instance with our custom PrometheusConfig and PrometheusController.
app = Litestar(route_handlers=[CustomPrometheusController], middleware=[prometheus_config.middleware])

Python 3.10+

Configuring the Prometheus Exporter

from typing import Any

from litestar import Litestar, Request
from litestar.contrib.prometheus import PrometheusConfig, PrometheusController


# We can modify the path of our custom handler and override the metrics format by subclassing the PrometheusController.
class CustomPrometheusController(PrometheusController):
    path = "/custom-path"
    openmetrics_format = True


# Let's assume this as our extra custom labels which we want our metrics to have.
# The values can be either a string or a callable that returns a string.
def custom_label_callable(request: Request[Any, Any, Any]) -> str:
    return "v2.0"


extra_labels = {
    "version_no": custom_label_callable,
    "location": "earth",
}

# Customizing the buckets for the histogram.
buckets = [0.1, 0.2, 0.3, 0.4, 0.5]


# Adding exemplars to the metrics.
# Note that this supported only in openmetrics format.
def custom_exemplar(request: Request[Any, Any, Any]) -> dict[str, str]:
    return {"trace_id": "1234"}


# Creating the instance of PrometheusConfig with our own custom options.
# The givenn options ara not necessary, you can use the default ones
# as well by just creating a raw instance PrometheusConfig()
prometheus_config = PrometheusConfig(
    app_name="litestar-example",
    prefix="litestar",
    labels=extra_labels,
    buckets=buckets,
    exemplars=custom_exemplar,
    excluded_http_methods=["POST"],
)


# Creating the litestar app instance with our custom PrometheusConfig and PrometheusController.
app = Litestar(route_handlers=[CustomPrometheusController], middleware=[prometheus_config.middleware])