Skip to content

Metrics API

The Metrics API exposes Prometheus-compatible metrics for monitoring and alerting.

Overview

CalcBridge exposes application metrics in Prometheus text format for scraping by monitoring infrastructure.

Endpoints

Prometheus Metrics

Returns all metrics in Prometheus exposition format.

GET /metrics

Response Headers

Content-Type: text/plain; charset=utf-8

Response

# HELP http_requests_total Total HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",endpoint="/api/v1/workbooks",status="200"} 1523
http_requests_total{method="POST",endpoint="/api/v1/calculations/evaluate",status="200"} 892

# HELP http_request_duration_seconds HTTP request latency
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{endpoint="/api/v1/workbooks",le="0.1"} 1400
http_request_duration_seconds_bucket{endpoint="/api/v1/workbooks",le="0.5"} 1520
http_request_duration_seconds_bucket{endpoint="/api/v1/workbooks",le="+Inf"} 1523

# HELP celery_task_duration_seconds Celery task processing time
# TYPE celery_task_duration_seconds histogram
celery_task_duration_seconds_bucket{task="parse_workbook",le="5"} 45
celery_task_duration_seconds_bucket{task="parse_workbook",le="30"} 50

# HELP db_connection_pool_size Database connection pool size
# TYPE db_connection_pool_size gauge
db_connection_pool_size{pool="default"} 10

# HELP rate_limit_exceeded_total Rate limit violations
# TYPE rate_limit_exceeded_total counter
rate_limit_exceeded_total{tier="free"} 23
rate_limit_exceeded_total{tier="standard"} 2

Authentication

Authentication is optional and configurable. When enabled, requires a Bearer token.

Responses

Status Description
200 Metrics in Prometheus format
401 Unauthorized (if auth required)
503 Metrics endpoint disabled

Metrics Health

Check if the metrics subsystem is healthy.

GET /metrics/health

Response

{
  "status": "healthy",
  "prometheus_enabled": true,
  "auth_required": false
}

Key Metrics

HTTP Metrics

Metric Type Description
http_requests_total counter Total HTTP requests by method, endpoint, status
http_request_duration_seconds histogram Request latency distribution
http_requests_in_progress gauge Currently processing requests

Task Metrics

Metric Type Description
celery_task_duration_seconds histogram Task processing time
celery_tasks_total counter Total tasks by name, status
celery_tasks_active gauge Currently executing tasks

Database Metrics

Metric Type Description
db_connection_pool_size gauge Connection pool size
db_connections_in_use gauge Active database connections
db_query_duration_seconds histogram Query execution time

Cache Metrics

Metric Type Description
valkey_operations_total counter Cache operations by command
valkey_hit_ratio gauge Cache hit ratio

Business Metrics

Metric Type Description
workbook_uploads_total counter Total workbook uploads
calculations_total counter Total formula evaluations
rate_limit_exceeded_total counter Rate limit violations by tier
compliance_tests_total counter Compliance tests executed

Prometheus Configuration

scrape_configs:
  - job_name: 'calcbridge-api'
    scrape_interval: 15s
    static_configs:
      - targets: ['api:8000']
    metrics_path: '/metrics'

Grafana Dashboards

Pre-built Grafana dashboards are available in config/grafana/:

Dashboard Description
API Overview Request rates, latency percentiles, error rates
Task Monitoring Celery task throughput and duration
Database Health Connection pool, query performance
Business Metrics Uploads, calculations, compliance tests