v2026.3.5 - Prometheus Metrics & Monitoring

​

Overview

​

Breaking Changes

​

New Features

​

📊 Prometheus Metrics Endpoint (/metrics)

• Full Prometheus text format support for scraping
• Automatic metrics collection via middleware
• Thread-safe metrics aggregation
• Zero external dependencies (pure Python implementation)

​

📈 HTTP Request Metrics

• Request counters by method, endpoint, and status code
• Request latency histogram (buckets: 0.1s, 0.5s, 1.0s, +Inf)
• Request/response body size tracking
• Concurrent requests gauge (in-flight monitoring)

​

⏱️ Task Performance Metrics

• Task duration histogram (buckets: 1s, 5s, 10s, 30s, 60s, +Inf)
• Active tasks gauge per agent
• Completed tasks counter by status (success, failed, canceled)
• Agent-specific task tracking

​

🚨 Error Tracking

• Error counters by agent and error type
• Support for timeout, validation, and execution errors
• Extensible error categorization

​

Metrics Exposed

​

Counter Metrics

​

Histogram Metrics

​

Gauge Metrics

​

Summary Metrics

• http_request_size_bytes
• http_response_size_bytes

​

Improvements

​

🏗️ Clean Architecture

• No circular dependencies (removed TYPE_CHECKING pattern)
• Clear separation of concerns:
  • metrics.py - Core metrics collection
  • middleware/metrics.py - HTTP request tracking
  • endpoints/metrics.py - Prometheus endpoint + agent metrics
• Proper dependency flow without circular imports

​

🔧 Middleware Integration

• MetricsMiddleware automatically tracks all HTTP requests
• Positioned last in middleware stack to capture complete request lifecycle
• Automatic request/response size calculation
• In-flight request tracking with proper cleanup

​

📖 Documentation

• Complete monitoring guide (docs/monitoring.md)
• Prometheus configuration example (examples/prometheus.yml)
• Grafana dashboard recommendations
• Example PromQL queries for common use cases

​

Technical Details

• Added: 6 files (metrics module, middleware, endpoint, tests, docs)
• Modified: 3 files (applications.py, init files, examples)
• Total: +591 insertions, -24 deletions

• bindu/server/metrics.py (284 lines)
• bindu/server/middleware/metrics.py (90 lines)
• bindu/server/endpoints/metrics.py (74 lines)
• tests/unit/test_metrics.py (106 lines)
• docs/monitoring.md (comprehensive guide)
• examples/prometheus.yml (configuration template)

​

Testing

​

Usage Examples

​

Access Metrics Endpoint

curl http://localhost:3773/metrics

​

Configure Prometheus (prometheus.yml)

scrape_configs:
  - job_name: 'bindu-agent'
    static_configs:
      - targets: ['localhost:3773']
    metrics_path: '/metrics'

​

Example PromQL Queries

# Request rate
rate(http_requests_total[5m])

# 95th percentile latency
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

# Error rate
rate(agent_errors_total[5m])

# Average task duration
rate(task_duration_seconds_sum[5m]) / rate(task_duration_seconds_count[5m])

​

Integration

​

Prometheus Setup

1. Install Prometheus: brew install prometheus
2. Configure scraping (see examples/prometheus.yml)
3. Start Prometheus: prometheus --config.file=prometheus.yml
4. Access UI: http://localhost:9090

​

Grafana Dashboard

1. Add Prometheus as data source
2. Create panels with PromQL queries
3. Recommended panels:
   • Request Rate (line graph)
   • Error Rate (line graph)
   • Latency Heatmap (histogram)
   • Active Tasks (gauge)
   • Task Completion (stacked area)

​

Migration Guide

1. No action required - metrics are automatically enabled
2. Access metrics at /metrics endpoint
3. Configure Prometheus to scrape your agent
4. Optional: Set up Grafana dashboards for visualization

​

Commit Details

• Add metrics_endpoint to endpoints module and register at /metrics route
• Implement MetricsMiddleware to capture request metrics
• Position metrics middleware last in stack to capture all requests
• Add logging for metrics middleware initialization
• Update examples formatting and premium advisor code style
• Create comprehensive monitoring documentation
• Add Prometheus configuration examples
• Implement thread-safe metrics collection
• Add unit tests for all metrics functionality