# rl-autoscale
🎯 **Production-ready metrics instrumentation for RL-based autoscaling systems**
A lightweight Python library that provides standardized Prometheus metrics for applications managed by reinforcement learning autoscalers. Works with Flask, FastAPI, and other Python web frameworks.
[](https://badge.fury.io/py/rl-autoscale)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## Features
✅ **One-Line Integration** - Add 2 lines of code, get full observability
✅ **Framework Agnostic** - Flask, FastAPI, Django support
✅ **Zero Overhead** - Minimal performance impact (<1ms per request)
✅ **Production Ready** - Battle-tested with proper error handling
✅ **RL Optimized** - Metrics designed specifically for RL autoscaling agents
✅ **Standardized** - Consistent metrics across all your microservices
## Quick Start
### Flask Application
```python
from flask import Flask
from rl_autoscale import enable_metrics
app = Flask(__name__)
# 🎯 ONE LINE - that's it!
enable_metrics(app, port=8000)
@app.route("/api/hello")
def hello():
return "Hello World"
if __name__ == "__main__":
app.run()
```
### FastAPI Application
```python
from fastapi import FastAPI
from rl_autoscale import enable_metrics
app = FastAPI()
# 🎯 ONE LINE - that's it!
enable_metrics(app, port=8000)
@app.get("/api/hello")
async def hello():
return {"message": "Hello World"}
```
## Installation
```bash
# Using pip
pip install rl-autoscale[flask] # For Flask apps
pip install rl-autoscale[fastapi] # For FastAPI apps
# Using uv (recommended - 10x faster!)
uv pip install rl-autoscale[flask]
uv pip install rl-autoscale[fastapi]
# Core only
pip install rl-autoscale
```
> 💡 **Tip**: This project uses [uv](https://github.com/astral-sh/uv) for blazingly fast package management. See [UV_GUIDE.md](UV_GUIDE.md) for details.
## What Metrics Are Exposed?
The library exports these standard Prometheus metrics:
### 1. `http_request_duration_seconds` (Histogram)
Request latency distribution used by RL agents to calculate percentiles (p50, p90, p99).
**Labels:**
- `method`: HTTP method (GET, POST, etc.)
- `path`: Request path (e.g., `/api/users`)
**Buckets:** Optimized for web APIs (5ms to 10s)
### 2. `http_requests_total` (Counter)
Total request count used for throughput analysis.
**Labels:**
- `method`: HTTP method
- `path`: Request path
- `http_status`: HTTP status code (200, 404, etc.)
## Advanced Usage
### Path Normalization
Prevent cardinality explosion by normalizing dynamic paths:
```python
from rl_autoscale import enable_metrics
from rl_autoscale.flask_middleware import normalize_api_paths
app = Flask(__name__)
enable_metrics(
app,
port=8000,
path_normalizer=normalize_api_paths # /user/123 -> /user/:id
)
```
### Custom Configuration
```python
enable_metrics(
app,
port=8000,
namespace="myapp", # Prefix metrics: myapp_http_request_duration_seconds
histogram_buckets=[0.001, 0.01, 0.1, 1.0, 10.0], # Custom buckets
exclude_paths=["/health", "/metrics", "/internal/*"], # Skip these paths
)
```
### Manual Instrumentation
For non-web workloads or custom metrics:
```python
from rl_autoscale import get_metrics_registry
metrics = get_metrics_registry()
# Record a custom operation
with timer():
result = expensive_operation()
duration = timer.elapsed()
metrics.observe_request(
method="BATCH",
path="/jobs/process",
duration=duration,
status_code=200
)
```
## Architecture
```
┌─────────────────┐
│ Your App │ ← Clean business logic (no metrics code!)
│ (Flask/ │
│ FastAPI) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ RL Metrics │ ← This library (automatic instrumentation)
│ Middleware │
└────────┬────────┘
│ HTTP :8000/metrics
▼
┌─────────────────┐
│ Prometheus │ ← Scrapes metrics every 15-60s
│ │
└────────┬────────┘
│ PromQL queries
▼
┌─────────────────┐
│ RL Agent │ ← Makes autoscaling decisions
│ (DQN/Q-Learning)│
└─────────────────┘
```
## Why This Library?
### Before (Without Library) ❌
```python
from prometheus_client import Counter, Histogram, start_http_server
# 50+ lines of boilerplate in EVERY service
REQUEST_LATENCY = Histogram(...)
REQUEST_COUNT = Counter(...)
@app.before_request
def before_request():
request.start_time = time.time()
@app.after_request
def after_request(response):
latency = time.time() - request.start_time
REQUEST_LATENCY.labels(...).observe(latency)
REQUEST_COUNT.labels(...).inc()
return response
start_http_server(8000)
# ... more boilerplate
```
### After (With Library) ✅
```python
from rl_autoscale import enable_metrics
enable_metrics(app, port=8000) # Done! 🎉
```
**Benefits:**
- ✅ **60+ lines → 1 line** - Massive code reduction
- ✅ **Standardized** - Same metrics across all services
- ✅ **Maintainable** - Update once, affects all services
- ✅ **Tested** - Production-ready error handling
- ✅ **Reusable** - Use in Flask, FastAPI, Django
## Configuration via Environment Variables
```bash
# Metrics port
export RL_METRICS_PORT=8000
# Custom namespace
export RL_METRICS_NAMESPACE=myapp
# Excluded paths (comma-separated)
export RL_METRICS_EXCLUDE_PATHS=/health,/metrics,/internal/*
```
## Kubernetes Deployment
Add Prometheus scrape annotations to your deployment:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
spec:
template:
metadata:
annotations:
prometheus.io/scrape: "true"
prometheus.io/port: "8000"
prometheus.io/path: "/metrics"
spec:
containers:
- name: app
image: myapp:latest
ports:
- containerPort: 5000 # App port
- containerPort: 8000 # Metrics port
```
## Prometheus Queries
Example queries for your RL agent:
```promql
# P90 response time over last 5 minutes
histogram_quantile(0.90,
rate(http_request_duration_seconds_bucket[5m])
)
# Requests per second
rate(http_requests_total[1m])
# Error rate (HTTP 5xx)
rate(http_requests_total{http_status=~"5.."}[5m])
```
## Performance
- **Overhead:** <1ms per request
- **Memory:** ~10MB baseline
- **CPU:** Negligible (<0.1% on most workloads)
Tested with 10,000 requests/second with zero performance degradation.
## Troubleshooting
### Port Already in Use
```python
# If port 8000 is taken, use another port
enable_metrics(app, port=8001)
```
### Metrics Not Showing Up
1. Check metrics endpoint: `curl http://localhost:8000/metrics`
2. Verify Prometheus can reach your app
3. Check Prometheus scrape config
4. Look for errors in application logs
### High Cardinality Warning
If you see thousands of unique metric labels:
```python
# Add path normalization
from rl_autoscale.flask_middleware import normalize_api_paths
enable_metrics(app, path_normalizer=normalize_api_paths)
```
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
```bash
# Clone repository
git clone https://github.com/ghazafm/rl-autoscale
cd rl-autoscale
# Setup with uv (recommended - one command!)
uv sync --all-extras
# Or traditional way with pip
pip install -e ".[dev,flask,fastapi]"
# Run tests
pytest
# Format and lint code (using ruff for both!)
ruff format .
ruff check .
```
> 📖 **Quick Start**: See [QUICK_START.md](QUICK_START.md) for fastest setup!
> 📖 **Developer Guide**: See [UV_GUIDE.md](UV_GUIDE.md) for using uv and ruff effectively.
## License
MIT License - See [LICENSE](LICENSE) file
## Support
- 📖 **Documentation:** https://github.com/ghazafm/rl-autoscale
- 🐛 **Issues:** https://github.com/ghazafm/rl-autoscale/issues
- 💬 **Discussions:** https://github.com/ghazafm/rl-autoscale/discussions
- 📦 **PyPI:** https://pypi.org/project/rl-autoscale/
---
**Made with ❤️ for RL Autoscaling Systems**
Raw data
{
"_id": null,
"home_page": null,
"name": "rl-autoscale",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "reinforcement-learning, autoscaling, kubernetes, prometheus, observability, metrics, rl, dqn, q-learning",
"author": null,
"author_email": "Fauzan Ghaza <contact@fauzanghaza.com>",
"download_url": "https://files.pythonhosted.org/packages/87/17/c82e3e249e9e94347d37b6adc2b4449b9403625efe0facfc4fdb7d9d7818/rl_autoscale-1.0.1.tar.gz",
"platform": null,
"description": "# rl-autoscale\n\n\ud83c\udfaf **Production-ready metrics instrumentation for RL-based autoscaling systems**\n\nA lightweight Python library that provides standardized Prometheus metrics for applications managed by reinforcement learning autoscalers. Works with Flask, FastAPI, and other Python web frameworks.\n\n[](https://badge.fury.io/py/rl-autoscale)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n## Features\n\n\u2705 **One-Line Integration** - Add 2 lines of code, get full observability\n\u2705 **Framework Agnostic** - Flask, FastAPI, Django support\n\u2705 **Zero Overhead** - Minimal performance impact (<1ms per request)\n\u2705 **Production Ready** - Battle-tested with proper error handling\n\u2705 **RL Optimized** - Metrics designed specifically for RL autoscaling agents\n\u2705 **Standardized** - Consistent metrics across all your microservices\n\n## Quick Start\n\n### Flask Application\n\n```python\nfrom flask import Flask\nfrom rl_autoscale import enable_metrics\n\napp = Flask(__name__)\n\n# \ud83c\udfaf ONE LINE - that's it!\nenable_metrics(app, port=8000)\n\n@app.route(\"/api/hello\")\ndef hello():\n return \"Hello World\"\n\nif __name__ == \"__main__\":\n app.run()\n```\n\n### FastAPI Application\n\n```python\nfrom fastapi import FastAPI\nfrom rl_autoscale import enable_metrics\n\napp = FastAPI()\n\n# \ud83c\udfaf ONE LINE - that's it!\nenable_metrics(app, port=8000)\n\n@app.get(\"/api/hello\")\nasync def hello():\n return {\"message\": \"Hello World\"}\n```\n\n## Installation\n\n```bash\n# Using pip\npip install rl-autoscale[flask] # For Flask apps\npip install rl-autoscale[fastapi] # For FastAPI apps\n\n# Using uv (recommended - 10x faster!)\nuv pip install rl-autoscale[flask]\nuv pip install rl-autoscale[fastapi]\n\n# Core only\npip install rl-autoscale\n```\n\n> \ud83d\udca1 **Tip**: This project uses [uv](https://github.com/astral-sh/uv) for blazingly fast package management. See [UV_GUIDE.md](UV_GUIDE.md) for details.\n\n## What Metrics Are Exposed?\n\nThe library exports these standard Prometheus metrics:\n\n### 1. `http_request_duration_seconds` (Histogram)\nRequest latency distribution used by RL agents to calculate percentiles (p50, p90, p99).\n\n**Labels:**\n- `method`: HTTP method (GET, POST, etc.)\n- `path`: Request path (e.g., `/api/users`)\n\n**Buckets:** Optimized for web APIs (5ms to 10s)\n\n### 2. `http_requests_total` (Counter)\nTotal request count used for throughput analysis.\n\n**Labels:**\n- `method`: HTTP method\n- `path`: Request path\n- `http_status`: HTTP status code (200, 404, etc.)\n\n## Advanced Usage\n\n### Path Normalization\n\nPrevent cardinality explosion by normalizing dynamic paths:\n\n```python\nfrom rl_autoscale import enable_metrics\nfrom rl_autoscale.flask_middleware import normalize_api_paths\n\napp = Flask(__name__)\n\nenable_metrics(\n app,\n port=8000,\n path_normalizer=normalize_api_paths # /user/123 -> /user/:id\n)\n```\n\n### Custom Configuration\n\n```python\nenable_metrics(\n app,\n port=8000,\n namespace=\"myapp\", # Prefix metrics: myapp_http_request_duration_seconds\n histogram_buckets=[0.001, 0.01, 0.1, 1.0, 10.0], # Custom buckets\n exclude_paths=[\"/health\", \"/metrics\", \"/internal/*\"], # Skip these paths\n)\n```\n\n### Manual Instrumentation\n\nFor non-web workloads or custom metrics:\n\n```python\nfrom rl_autoscale import get_metrics_registry\n\nmetrics = get_metrics_registry()\n\n# Record a custom operation\nwith timer():\n result = expensive_operation()\n duration = timer.elapsed()\n\nmetrics.observe_request(\n method=\"BATCH\",\n path=\"/jobs/process\",\n duration=duration,\n status_code=200\n)\n```\n\n## Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Your App \u2502 \u2190 Clean business logic (no metrics code!)\n\u2502 (Flask/ \u2502\n\u2502 FastAPI) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u25bc\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 RL Metrics \u2502 \u2190 This library (automatic instrumentation)\n\u2502 Middleware \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 HTTP :8000/metrics\n \u25bc\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Prometheus \u2502 \u2190 Scrapes metrics every 15-60s\n\u2502 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 PromQL queries\n \u25bc\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 RL Agent \u2502 \u2190 Makes autoscaling decisions\n\u2502 (DQN/Q-Learning)\u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n## Why This Library?\n\n### Before (Without Library) \u274c\n```python\nfrom prometheus_client import Counter, Histogram, start_http_server\n\n# 50+ lines of boilerplate in EVERY service\nREQUEST_LATENCY = Histogram(...)\nREQUEST_COUNT = Counter(...)\n\n@app.before_request\ndef before_request():\n request.start_time = time.time()\n\n@app.after_request\ndef after_request(response):\n latency = time.time() - request.start_time\n REQUEST_LATENCY.labels(...).observe(latency)\n REQUEST_COUNT.labels(...).inc()\n return response\n\nstart_http_server(8000)\n# ... more boilerplate\n```\n\n### After (With Library) \u2705\n```python\nfrom rl_autoscale import enable_metrics\n\nenable_metrics(app, port=8000) # Done! \ud83c\udf89\n```\n\n**Benefits:**\n- \u2705 **60+ lines \u2192 1 line** - Massive code reduction\n- \u2705 **Standardized** - Same metrics across all services\n- \u2705 **Maintainable** - Update once, affects all services\n- \u2705 **Tested** - Production-ready error handling\n- \u2705 **Reusable** - Use in Flask, FastAPI, Django\n\n## Configuration via Environment Variables\n\n```bash\n# Metrics port\nexport RL_METRICS_PORT=8000\n\n# Custom namespace\nexport RL_METRICS_NAMESPACE=myapp\n\n# Excluded paths (comma-separated)\nexport RL_METRICS_EXCLUDE_PATHS=/health,/metrics,/internal/*\n```\n\n## Kubernetes Deployment\n\nAdd Prometheus scrape annotations to your deployment:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n name: my-app\nspec:\n template:\n metadata:\n annotations:\n prometheus.io/scrape: \"true\"\n prometheus.io/port: \"8000\"\n prometheus.io/path: \"/metrics\"\n spec:\n containers:\n - name: app\n image: myapp:latest\n ports:\n - containerPort: 5000 # App port\n - containerPort: 8000 # Metrics port\n```\n\n## Prometheus Queries\n\nExample queries for your RL agent:\n\n```promql\n# P90 response time over last 5 minutes\nhistogram_quantile(0.90,\n rate(http_request_duration_seconds_bucket[5m])\n)\n\n# Requests per second\nrate(http_requests_total[1m])\n\n# Error rate (HTTP 5xx)\nrate(http_requests_total{http_status=~\"5..\"}[5m])\n```\n\n## Performance\n\n- **Overhead:** <1ms per request\n- **Memory:** ~10MB baseline\n- **CPU:** Negligible (<0.1% on most workloads)\n\nTested with 10,000 requests/second with zero performance degradation.\n\n## Troubleshooting\n\n### Port Already in Use\n\n```python\n# If port 8000 is taken, use another port\nenable_metrics(app, port=8001)\n```\n\n### Metrics Not Showing Up\n\n1. Check metrics endpoint: `curl http://localhost:8000/metrics`\n2. Verify Prometheus can reach your app\n3. Check Prometheus scrape config\n4. Look for errors in application logs\n\n### High Cardinality Warning\n\nIf you see thousands of unique metric labels:\n\n```python\n# Add path normalization\nfrom rl_autoscale.flask_middleware import normalize_api_paths\n\nenable_metrics(app, path_normalizer=normalize_api_paths)\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n```bash\n# Clone repository\ngit clone https://github.com/ghazafm/rl-autoscale\ncd rl-autoscale\n\n# Setup with uv (recommended - one command!)\nuv sync --all-extras\n\n# Or traditional way with pip\npip install -e \".[dev,flask,fastapi]\"\n\n# Run tests\npytest\n\n# Format and lint code (using ruff for both!)\nruff format .\nruff check .\n```\n\n> \ud83d\udcd6 **Quick Start**: See [QUICK_START.md](QUICK_START.md) for fastest setup!\n> \ud83d\udcd6 **Developer Guide**: See [UV_GUIDE.md](UV_GUIDE.md) for using uv and ruff effectively.\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file\n\n## Support\n\n- \ud83d\udcd6 **Documentation:** https://github.com/ghazafm/rl-autoscale\n- \ud83d\udc1b **Issues:** https://github.com/ghazafm/rl-autoscale/issues\n- \ud83d\udcac **Discussions:** https://github.com/ghazafm/rl-autoscale/discussions\n- \ud83d\udce6 **PyPI:** https://pypi.org/project/rl-autoscale/\n\n---\n\n**Made with \u2764\ufe0f for RL Autoscaling Systems**\n",
"bugtrack_url": null,
"license": null,
"summary": "Production-ready metrics instrumentation for RL-based autoscaling systems",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/ghazafm/rl-autoscale/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/ghazafm/rl-autoscale#readme",
"Homepage": "https://github.com/ghazafm/rl-autoscale",
"Issues": "https://github.com/ghazafm/rl-autoscale/issues",
"Repository": "https://github.com/ghazafm/rl-autoscale"
},
"split_keywords": [
"reinforcement-learning",
" autoscaling",
" kubernetes",
" prometheus",
" observability",
" metrics",
" rl",
" dqn",
" q-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "10b76f18f23c546e00597215dd50a25b5cc7d864f964fbbfb004400611046e5a",
"md5": "a624f11f91703a31d8eb0ea85f864dd7",
"sha256": "033abbcb277095d942e89555e07f2cb25d76bd3ab3c7c3077acd71f8fa221697"
},
"downloads": -1,
"filename": "rl_autoscale-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a624f11f91703a31d8eb0ea85f864dd7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11891,
"upload_time": "2025-11-07T15:28:16",
"upload_time_iso_8601": "2025-11-07T15:28:16.548865Z",
"url": "https://files.pythonhosted.org/packages/10/b7/6f18f23c546e00597215dd50a25b5cc7d864f964fbbfb004400611046e5a/rl_autoscale-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8717c82e3e249e9e94347d37b6adc2b4449b9403625efe0facfc4fdb7d9d7818",
"md5": "67cfec374379feedf4a1915f69e462b1",
"sha256": "d6d94b002e9b7a51eb4fc4fa5db06a3696d2396e76f2c2fcedfcdc1f11ed72c2"
},
"downloads": -1,
"filename": "rl_autoscale-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "67cfec374379feedf4a1915f69e462b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15225,
"upload_time": "2025-11-07T15:28:17",
"upload_time_iso_8601": "2025-11-07T15:28:17.898016Z",
"url": "https://files.pythonhosted.org/packages/87/17/c82e3e249e9e94347d37b6adc2b4449b9403625efe0facfc4fdb7d9d7818/rl_autoscale-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-07 15:28:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ghazafm",
"github_project": "rl-autoscale",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rl-autoscale"
}
JSON
