prometheus

class litestar.plugins.prometheus.PrometheusConfig

Bases: object

Configuration class for the PrometheusConfig middleware.

__init__(app_name: str = 'litestar', prefix: str = 'litestar', labels: Mapping[str, str | Callable] | None = None, exemplars: Callable[[Request], dict] | None = None, buckets: Sequence[str | float] | None = None, excluded_http_methods: Method | Sequence[Method] | None = None, exclude_unhandled_paths: bool = False, exclude: str | list[str] | None = None, exclude_opt_key: str | None = None, scopes: Scopes | None = None, middleware_class: type[PrometheusMiddleware] = <class 'litestar.plugins.prometheus.middleware.PrometheusMiddleware'>, group_path: bool = True) → None

app_name: str = 'litestar'

The name of the application to use in the metrics.

buckets: Sequence[str | float] | None = None

A list of buckets to use for the histogram.

exclude: str | list[str] | None = None

A pattern or list of patterns for routes to exclude from the metrics.

exclude_opt_key: str | None = None

A key or list of keys in opt with which a route handler can “opt-out” of the middleware.

exclude_unhandled_paths: bool = False

Whether to ignore requests for unhandled paths from the metrics.

excluded_http_methods: Method | Sequence[Method] | None = None

A list of http methods to exclude from the metrics.

exemplars: Callable[[Request], dict] | None = None

A callable that returns a list of exemplars to add to the metrics. Only supported in opementrics-text exposition format.

group_path: bool = True

Whether to group paths in the metrics to avoid cardinality explosion.

labels: Mapping[str, str | Callable] | None = None

A mapping of labels to add to the metrics. The values can be either a string or a callable that returns a string.

property middleware: PrometheusMiddleware

Create an instance of PrometheusMiddleware, or a subclass of this middleware, configured from this config instance.

Returns:

An instance of middleware_class.

middleware_class

alias of PrometheusMiddleware

prefix: str = 'litestar'

The prefix to use for the metrics.

scopes: Scopes | None = None

ASGI scopes processed by the middleware, if None both http and websocket will be processed.

class litestar.plugins.prometheus.PrometheusController

Bases: Controller

Controller for Prometheus endpoints.

after_request: AfterRequestHookHandler | None

A sync or async function executed before a Request is passed to any route handler.

If this function returns a value, the request will not reach the route handler, and instead this value will be used.

after_response: AfterResponseHookHandler | None

A sync or async function called after the response has been awaited.

It receives the Request instance and should not return any values.

before_request: BeforeRequestHookHandler | None

A sync or async function called immediately before calling the route handler.

It receives the Request instance and any non-None return value is used for the response, bypassing the route handler.

cache_control: CacheControlHeader | None

A CacheControlHeader header to add to route handlers of this controller.

Can be overridden by route handlers.

dependencies: Dependencies | None

A string keyed dictionary of dependency Provider instances.

dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for (de)serializing and validation of request data.

etag: ETag | None

An etag header of type ETag to add to route handlers of this controller.

Can be overridden by route handlers.

exception_handlers: ExceptionHandlersMap | None

A map of handler functions to status codes and/or exception types.

guards: Sequence[Guard] | None

A sequence of Guard callables.

include_in_schema: bool | EmptyType

A boolean flag dictating whether the route handler should be documented in the OpenAPI schema

middleware: Sequence[Middleware] | None

A sequence of Middleware.

opt: Mapping[str, Any] | None

A string key mapping of arbitrary values that can be accessed in Guards or wherever you have access to Request or ASGI Scope.

parameters: ParametersMap | None

A mapping of Parameter definitions available to all application paths.

path: str

The path to expose the metrics on.

request_class: type[Request] | None

A custom subclass of Request to be used as the default request for all route handlers under the controller.

request_max_body_size: int | None | EmptyType

Maximum allowed size of the request body in bytes. If this size is exceeded, a ‘413 - Request Entity Too Large’ error response is returned.

response_class: type[Response] | None

A custom subclass of Response to be used as the default response for all route handlers under the controller.

response_cookies: ResponseCookies | None

A list of Cookie instances.

response_headers: ResponseHeaders | None

A string keyed dictionary mapping ResponseHeader instances.

return_dto: type[AbstractDTO] | None | EmptyType

AbstractDTO to use for serializing outbound response data.

security: Sequence[SecurityRequirement] | None

A sequence of dictionaries that to the schema of all route handlers under the controller.

signature_namespace: dict[str, Any]

A mapping of names to types for use in forward reference resolution during signature modelling.

signature_types: Sequence[Any]

A sequence of types for use in forward reference resolution during signature modelling.

These types will be added to the signature namespace using their __name__ attribute.

tags: Sequence[str] | None

A sequence of string tags that will be appended to the schema of all route handlers under the controller.

type_decoders: TypeDecodersSequence | None

A sequence of tuples, each composed of a predicate testing for type identity and a msgspec hook for deserialization.

type_encoders: TypeEncodersMap | None

A mapping of types to callables that transform them into types supported for serialization.

websocket_class: type[WebSocket] | None

A custom subclass of WebSocket to be used as the default websocket for all route handlers under the controller.

openmetrics_format: bool = False

Whether to expose the metrics in OpenMetrics format.

class litestar.plugins.prometheus.PrometheusMiddleware

Bases: ASGIMiddleware

Prometheus Middleware.

__init__(*, app_name: str = 'litestar', prefix: str = 'litestar', labels: Mapping[str, str | Callable] | None = None, exemplars: Callable[[Request], dict] | None = None, buckets: Sequence[str | float] | None = None, excluded_http_methods: Method | Sequence[Method] | None = None, exclude: str | list[str] | None = None, exclude_opt_key: str | None = None, scopes: Scopes | None = None, group_path: bool = True) → None

Middleware that adds Prometheus instrumentation to the application.

Parameters:

• app_name – The name of the application to use in the metrics.

• prefix – The prefix to use for the metrics.

• labels – A mapping of labels to add to the metrics. The values can be either a string or a callable that returns a string.

• exemplars – A callable that returns a list of exemplars to add to the metrics. Only supported in openmetrics-text exposition format.

• buckets – A list of buckets to use for the histogram.

• excluded_http_methods – A list of http methods to exclude from the metrics.

• exclude – A pattern or list of patterns for routes to exclude from the metrics, matched against the handler path.

• exclude_opt_key – A key in opt with which a route handler can “opt-out” of the middleware.

• scopes – ASGI scopes processed by the middleware; if None or empty, http, websocket and ASGI route handlers are all processed. Mounted ASGI apps stay wrapped regardless, with their connections filtered by scope type.

• group_path – Whether to group paths in the metrics to avoid cardinality explosion.

async handle(scope: Scope, receive: Receive, send: Send, next_app: ASGIApp) → None

Handle ASGI call.

Parameters:

• scope – The ASGI connection scope.

• receive – The ASGI receive function.

• send – The ASGI send function.

• next_app – The next ASGI application in the middleware stack to call.

Returns:

None