The application exposes Prometheus metrics at GET /metrics. This endpoint is
not authenticated and should only be reachable by Prometheus through a trusted
network or reverse-proxy rule.
Application metrics include normalized Flask route traffic and Socket.IO event traffic. Query text, feed IDs, DOI values, and other user-controlled values are never used as metric labels.
An import-ready Grafana dashboard is available in
miage-scholar-grafana-dashboard.json. During import, select the Prometheus
datasource that scrapes this application's /metrics endpoint.
Useful PromQL queries:
# Request rate
sum(rate(miage_scholar_http_requests_total[5m]))
# HTTP 5xx ratio
sum(rate(miage_scholar_http_requests_total{status=~"5.."}[5m]))
/
clamp_min(sum(rate(miage_scholar_http_requests_total[5m])), 0.000001)
# HTTP p95 latency
histogram_quantile(
0.95,
sum by (le) (rate(miage_scholar_http_request_duration_seconds_bucket[5m]))
)
# Application process restarts observed during the last 24 hours
changes(miage_scholar_process_start_time_seconds[24h])
Socket.IO errors can be monitored with:
sum(rate(miage_scholar_socketio_events_total{outcome="error"}[5m])) by (event)
Provider query rates and uncached result throughput:
sum(rate(miage_scholar_provider_queries_total[5m])) by (provider)
sum(rate(miage_scholar_provider_uncached_results_total[5m])) by (provider)
# Papers returned by each provider, including cached responses
sum(rate(miage_scholar_provider_papers_retrieved_total[5m])) by (provider)
Cache hit ratio by provider:
sum(rate(miage_scholar_provider_cache_lookups_total{outcome="hit"}[5m])) by (provider)
/
clamp_min(
sum(rate(miage_scholar_provider_cache_lookups_total[5m])) by (provider),
0.000001
)
provider_queries_total counts logical API operations, including cache hits.
provider_papers_retrieved_total counts papers returned from successful cached
and uncached provider responses.
provider_uncached_results_total counts records in successful responses obtained
after cache misses. Provider retries remain part of the same logical operation.
The restart query assumes the production configuration of one Gunicorn worker. Prometheus multiprocess mode is required before increasing the worker count.