Registry / observability / prometheus-fastapi-instrumentator

prometheus-fastapi-instrumentator

library8.1.0pypypi✓ verified 27d ago

This library provides a straightforward way to instrument your FastAPI or Starlette applications with Prometheus metrics. It automatically exposes common HTTP request metrics and allows for custom metric definitions. Currently at version 7.1.0, it maintains an active development pace with frequent updates and bug fixes, typically releasing minor versions every few months and major versions annually.

observability web-framework aws gcp azure

pip install prometheus-fastapi-instrumentator prometheus_client uvicorn

github ↗package ↗

INSTALL

IMPORT

SIG · PROMETHEUS-FASTAPI

prometheus-fastapi-instrumentator

observabilitypythonv8.1.0

Install

2.3s avg

Import

500ms

Disk

21MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v8.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.528s · 23.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.3s · import 0.472s · 24MB

21MB installed

● package 21MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Instrumentator

✓ from prometheus_fastapi_instrumentator import Instrumentator

This quickstart initializes a FastAPI app, instruments it with default Prometheus metrics on startup, and exposes a `/metrics` endpoint. Run `python your_app.py` and navigate to `http://localhost:8000/metrics` to see the metrics. It also includes comments on important considerations for multiprocessing.

from fastapi import FastAPI from prometheus_fastapi_instrumentator import Instrumentator import uvicorn import os app = FastAPI() # Best practice: Instrument the app on startup @app.on_event("startup") async def startup_event(): Instrumentator().instrument(app).expose(app) print("Prometheus metrics exposed at /metrics") @app.get("/") async def read_root(): return {"message": "Hello Prometheus!"} @app.get("/items/{item_id}") async def read_item(item_id: int): return {"item_id": item_id, "message": "An item"} if __name__ == "__main__": # For multiprocessing environments (e.g., Gunicorn with multiple workers), # PROMETHEUS_MULTIPROC_DIR must be set to a shared writable directory. # Example: os.environ["PROMETHEUS_MULTIPROC_DIR"] = "/tmp/prom_data" uvicorn.run(app, host="0.0.0.0", port=8000)

Debug

Known issues

breakingPython 3.7 is no longer supported as of version 7.0.0. Applications running on Python 3.7 will fail.

fix

Upgrade your Python environment to 3.8 or newer.

affects: >=7.0.0

breakingAccessing `info.response.body` in custom instrumentation functions is disabled by default in version 6.0.0 due to performance and security concerns.

fix

If absolutely necessary, re-enable this feature by setting `enable_body_in_metrics=True` in the `Instrumentator` constructor (e.g., `Instrumentator(enable_body_in_metrics=True)`). Exercise caution when re-enabling.

affects: >=6.0.0

deprecatedThe lowercase `prometheus_multiproc_dir` environment variable was deprecated in version 5.10.0.

fix

Use the uppercase `PROMETHEUS_MULTIPROC_DIR` environment variable for configuring multiprocessing support. The lowercase version might eventually be removed.

affects: >=5.10.0

gotchaFor reliable startup and to avoid potential issues during reloads or when using certain ASGI servers, instrumentation should occur within an `@app.on_event("startup")` function.

fix

Wrap your `Instrumentator().instrument(app).expose(app)` call inside an `async def startup_event():` function decorated with `@app.on_event("startup")`.

affects: All versions

gotchaWhen running FastAPI with multiple worker processes (e.g., using Gunicorn), Prometheus metrics require special handling. The `PROMETHEUS_MULTIPROC_DIR` environment variable must be set to a shared, writable directory.

fix

Before starting your application, set the `PROMETHEUS_MULTIPROC_DIR` environment variable (e.g., `export PROMETHEUS_MULTIPROC_DIR=/tmp/prom_data`). Ensure this directory exists and is writable by all worker processes.

affects: All versions

Upgrade

Version history

8.1.0latest on PyPI · released Jul 26, 2026

Audit

Dependencies

fastapirequiredPrimary framework for instrumentation, though it also supports Starlette.

prometheus_clientrequiredCore library for creating and exposing Prometheus metrics.

uvicornoptionalCommon ASGI server used for running FastAPI applications, useful for quickstarts.

Agent activity

65 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/trallnag/prometheus-fastapi-instrumentator ↗

packagehttps://pypi.org/project/prometheus-fastapi-instrumentator/ ↗