Prometheus Metrics and Monitoring
Relevant source files
The following files were used as context for generating this wiki page:
FastLimit includes built-in support for Prometheus metrics to provide comprehensive observability into rate limiting performance, usage patterns, and system health. This monitoring system is designed to track latency, request throughput, rate limit violations, and backend Redis performance.
The metrics module is an optional dependency that requires the prometheus-client package. When enabled, it allows developers to expose a standard /metrics endpoint in their applications, enabling integration with monitoring tools like Prometheus and Grafana.
Sources: fastlimit/metrics.py:1-12, README.md:162-167
Architecture and Components
The monitoring system is built around the RateLimitMetrics class, which serves as a centralized collector. It utilizes standard Prometheus metric types—Counters, Gauges, and Histograms—to record different aspects of the system's operation.
Metrics Collection Flow
The following diagram illustrates how metrics are captured during a standard rate limit check operation:
This flow ensures that metrics collection happens transparently alongside the core rate limiting logic.
Sources: fastlimit/metrics.py:121-180, fastlimit/limiter.py
Dependency Management
Metrics support is optional. The system checks for the availability of prometheus_client at runtime. If the library is missing, metrics collection is gracefully disabled with a warning log.
Sources: fastlimit/metrics.py:18-28, fastlimit/init.py:41-48
Core Metrics
FastLimit categorizes its metrics into four primary areas: rate limit checks, violations, backend performance, and usage tracking.
Rate Limit Check Metrics
These metrics track the volume and latency of the core check() operations.
| Metric Name | Type | Labels | Description |
|---|---|---|---|
fastlimit_checks_total | Counter | algorithm, result | Total number of checks performed (allowed vs denied). |
fastlimit_check_duration_seconds | Histogram | algorithm | Time spent performing rate limit checks. |
Sources: fastlimit/metrics.py:87-101, README.md:170-174
Backend and Redis Metrics
These metrics monitor the health and performance of the Redis storage layer and the execution of Lua scripts.
| Metric Name | Type | Labels | Description |
|---|---|---|---|
fastlimit_backend_operations_total | Counter | operation, status | Count of backend tasks (e.g., check, reset). |
fastlimit_backend_operation_duration_seconds | Histogram | operation | Latency of backend operations. |
fastlimit_redis_operations_total | Counter | command, status | Specific Redis command success/failure counts. |
fastlimit_redis_script_executions_total | Counter | script_name, execution_type | Tracks evalsha (cached) vs eval (uncached) executions. |
fastlimit_active_redis_connections | Gauge | None | Number of active Redis connections. |
Sources: fastlimit/metrics.py:108-142, README.md:175
Configuration and Initialization
Metrics collection is disabled by default and must be explicitly enabled during the RateLimiter initialization.
Initialization Parameters
The RateLimiter constructor accepts configuration for metrics through the following parameters:
limiter = RateLimiter(
redis_url="redis://localhost:6379",
enable_metrics=True, # Must be True to start collection
key_prefix="ratelimit"
)
Sources: README.md:135-144, fastlimit/metrics.py:68-83
Manual Metric Expose
To expose metrics in a FastAPI application, the prometheus_client utility generate_latest is used within a route:
from prometheus_client import generate_latest, CONTENT_TYPE_LATEST
from fastapi import FastAPI, Response
@app.get("/metrics")
async def metrics():
return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)
Sources: fastlimit/metrics.py:53-65, examples/fastapi_app.py
Internal Tracking Mechanisms
The system employs Python context managers and decorators to ensure accurate timing and status recording without polluting business logic.
Context Managers
The RateLimitMetrics class provides two primary context managers:
track_check_duration: Measures the total time for a check operation including logic and networking.track_backend_operation: Specifically measures the time spent interacting with the Redis backend.
The Metrics Decorator
The metrics_decorator is a utility function used to wrap backend methods. It automatically handles timing and status increments for both synchronous and asynchronous functions.
def metrics_decorator(metrics: Optional[RateLimitMetrics], operation: str):
# Wraps functions to track backend duration and success/error status
...
Sources: fastlimit/metrics.py:151-180, fastlimit/metrics.py:255-288
Conclusion
Prometheus integration in FastLimit provides a robust observability layer. By tracking everything from high-level request results to low-level Redis Lua script cache hits (evalsha), it allows operators to fine-tune rate limiting algorithms and ensure backend stability under heavy load.