Skip to content

Adapters

Flask

Flask adapter: request hooks, exceptions, sampling, and bytes in/out.

Usage

from profilis.flask.adapter import ProfilisFlask app = Flask(name) ProfilisFlask(app, collector=my_collector, exclude_routes=["/health", "/metrics"], sample=1.0)

Guarantees: - One REQ metric per request (success or error) with route template if available - Exceptions recorded with exception_type - Bytes in/out captured best-effort

ProfilisFlask

Built-in UI: JSON endpoint + HTML dashboard (Flask).

  • /metrics.json -> StatsStore snapshot
  • /errors.json -> recent error ring (last N)
  • / -> HTML dashboard with KPIs + sparkline, theme toggle, recent errors table
  • Supports bearer token auth (optional), saves token from ?token to localStorage
  • Configurable ui_enabled and ui_prefix

Uses shared UI from profilis.ui (ErrorItem, record_error, DASHBOARD_HTML).

FastAPI

Thin FastAPI adapter on top of the ASGI middleware.

This module provides a convenience function instrument_fastapi which registers the ProfilisASGIMiddleware with a FastAPI app and ensures route templates are captured reliably (APIRouter, mounted apps, dependencies). It intentionally does not re-implement timing logic — it delegates to ProfilisASGIMiddleware.

instrument_fastapi(app, emitter, config=None, *, route_excludes=None)

Instrument a FastAPI app with Profilis ASGI middleware.

  • Registers ProfilisASGIMiddleware as outer middleware so it observes the final Starlette/FastAPI response lifecycle (captures http.response.start).
  • Accepts optional route_excludes to skip recording certain paths (e.g., mounted UI).
  • Works with APIRouter, dependency-injected endpoints, background tasks, and streaming responses.

Built-in UI: JSON endpoints + HTML dashboard (FastAPI).

  • /metrics.json -> StatsStore snapshot
  • /errors.json -> recent error ring (last N)
  • / -> HTML dashboard with KPIs + sparkline, theme toggle, recent errors table
  • Supports bearer token auth (optional), saves token from ?token to localStorage
  • Configurable prefix when including the router

Uses shared UI from profilis.ui (ErrorItem, record_error, DASHBOARD_HTML).

make_ui_router(stats, *, bearer_token=None, prefix='')

Create a FastAPI APIRouter that serves the Profilis dashboard and JSON endpoints.

Usage

stats = StatsStore() router = make_ui_router(stats, prefix="/profilis") app.include_router(router)

Sanic

Sanic native adapter for Profilis.

  • Registers request/response/exception middleware that records HTTP metrics.
  • Optionally mounts an ASGI UI app at a given path (best-effort; depends on Sanic version).

instrument_sanic_app(app, emitter, config=None, *, mount_asgi_app=None, mount_path='/profilis')

Attach Profilis middleware to a Sanic app.

  • app: a Sanic instance
  • emitter: Emitter instance
  • config: SanicConfig
  • mount_asgi_app: optional ASGI app (callable) to mount at mount_path if Sanic supports mounting ASGI apps
  • mount_path: where to mount the ASGI app if provided

The function registers request / response / exception middleware on the app.

Built-in UI: JSON endpoints + HTML dashboard (Sanic).

  • /metrics.json -> StatsStore snapshot
  • /errors.json -> recent error ring (last N)
  • / -> HTML dashboard with KPIs + sparkline, theme toggle, recent errors table
  • Supports bearer token auth (optional), saves token from ?token to localStorage
  • Configurable ui_prefix (mounted via Sanic Blueprint)

Uses shared UI from profilis.ui (ErrorItem, record_error, DASHBOARD_HTML).

make_ui_blueprint(stats, *, bearer_token=None, ui_prefix='')

Create a Sanic Blueprint that serves the Profilis dashboard and JSON endpoints.

Usage

stats = StatsStore() bp = make_ui_blueprint(stats, ui_prefix="/profilis") app.blueprint(bp)

ASGI (generic)

ASGI middleware for Starlette (and other ASGI frameworks) that records HTTP metrics.

Features: - Intercepts 'http' scopes only (skips websocket) - Resolves route path from scope['route'].path_format when available - Captures method, path/route, status, latency (ns), exception type when present - Uses profilis runtime context to allow trace/span propagation - Configurable sampling, route excludes (prefix/regex), per-route overrides, always-sample-errors (5xx)

ASGIConfig

__init__(*, sampling_rate=1.0, route_excludes=None, route_overrides=None, always_sample_errors=True, random_seed=None, rng=None)

float in [0.0, 1.0] probability of capturing a request.

1.0 captures all; 0.0 captures none (except 5xx if always_sample_errors).

route_excludes: iterable of route prefixes or exact strings to skip; use "re:..." for regex. route_overrides: iterable of (pattern, rate) for per-route sampling; first match wins; "re:..." for regex. always_sample_errors: if True, 5xx and exceptions are always recorded. random_seed: optional seed for deterministic sampling (tests). rng: optional callable () -> float in [0,1) for deterministic tests; overrides random_seed if set.

ProfilisASGIMiddleware

ASGI middleware that records HTTP request metrics and enqueues them via Emitter.

Usage

app = Starlette() emitter = Emitter(AsyncCollector(...)) middleware = ProfilisASGIMiddleware(app, emitter, ASGIConfig(...)) app.add_middleware(middleware) # or mount wrapper in frameworks

RequestInfo dataclass

Container for request information.