Monitoring

CleverThis emits OpenTelemetry traces and Prometheus metrics. This page covers configuring observability for production deployments.

OpenTelemetry traces

The API server is instrumented with OpenTelemetry. Every incoming request creates a trace span, with child spans for database queries, provider API calls, and Actor execution steps. This gives you end-to-end visibility into request latency and failure points.

Enable trace export by setting:

TELEMETRY_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://your-otel-collector:4317
OTEL_SERVICE_NAME=cleverthis-api

CleverThis supports any OTLP-compatible backend: Jaeger, Tempo, SigNoz, Honeycomb, Datadog, etc.

SigNoz (recommended for self-hosters)

SigNoz is an open-source observability platform that accepts OTLP. To run SigNoz alongside CleverThis:

git clone https://github.com/SigNoz/signoz.git
cd signoz/deploy
docker compose up -d

Then set OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317 in your CleverThis .env.

Prometheus metrics

The API server exposes a /metrics endpoint in Prometheus exposition format. Scrape it with your Prometheus instance:

# prometheus.yml
scrape_configs:
  - job_name: cleverthis-api
    static_configs:
      - targets: ["api:8000"]

Key metrics:

Metric	Type	Description
cleverthis_requests_total	Counter	Total inference requests by model and namespace
cleverthis_tokens_total	Counter	Total tokens consumed, labeled by type (prompt/completion)
cleverthis_request_duration_seconds	Histogram	End-to-end request latency
cleverthis_provider_errors_total	Counter	Provider error count by provider and error type
cleverthis_actor_steps_total	Counter	Actor execution steps by actor and agent type

Health check endpoints

Path	Description
GET /health	Returns 200 if the API server is running
GET /health/db	Returns 200 if the database connection is healthy
GET /health/redis	Returns 200 if the Redis connection is healthy

Use these for load balancer health checks and Kubernetes liveness/readiness probes.

Coming soon

Pre-built Grafana dashboards for CleverThis metrics are being published to the Grafana dashboard registry.