Skip to content

# RAG Metrics & Dashboard Plan

План збору метрик та створення дашборду для RAG + Memory стеку.

## 1. Метрики для збору

### 1.1. RAG Service Metrics

Ingest Metrics: - `rag_ingest_total` - загальна кількість ingest операцій - `rag_ingest_duration_seconds` - час ingest (histogram) - `rag_ingest_documents_indexed` - кількість індексованих документів - `rag_ingest_pages_processed` - кількість оброблених сторінок - `rag_ingest_errors_total` - кількість помилок ingest

Query Metrics: - `rag_query_total` - загальна кількість запитів - `rag_query_duration_seconds` - час query (histogram) - `rag_query_documents_retrieved` - кількість знайдених документів - `rag_query_citations_count` - кількість citations - `rag_query_embedding_time_seconds` - час embedding - `rag_query_retrieval_time_seconds` - час retrieval - `rag_query_llm_time_seconds` - час LLM генерації - `rag_query_errors_total` - кількість помилок query - `rag_query_empty_results_total` - запити без результатів

Quality Metrics: - `rag_query_dao_filter_applied` - застосування dao_id фільтра - `rag_query_doc_ids_found` - унікальні doc_ids в результатах

### 1.2. Router Metrics (RAG Query Mode)

- `router_rag_query_total` - загальна кількість rag_query запитів
- `router_rag_query_duration_seconds` - загальний час обробки
- `router_rag_query_memory_used` - використання Memory
- `router_rag_query_rag_used` - використання RAG
- `router_rag_query_prompt_tokens_estimated` - оцінка токенів промпту
- `router_rag_query_fallback_total` - fallback на Memory only

### 1.3. Memory Service Metrics

- `memory_context_fetch_total` - кількість викликів get_context
- `memory_context_fetch_duration_seconds` - час отримання контексту
- `memory_context_facts_count` - кількість facts
- `memory_context_events_count` - кількість events
- `memory_context_summaries_count` - кількість summaries

## 2. Де збирати метрики

### 2.1. RAG Service

Файл: `services/rag-service/app/metrics.py`

    from prometheus_client import Counter, Histogram, Gauge

    # Ingest metrics
    ingest_total = Counter('rag_ingest_total', 'Total ingest operations')
    ingest_duration = Histogram('rag_ingest_duration_seconds', 'Ingest duration')
    ingest_documents = Counter('rag_ingest_documents_indexed', 'Documents indexed')
    ingest_errors = Counter('rag_ingest_errors_total', 'Ingest errors')

    # Query metrics
    query_total = Counter('rag_query_total', 'Total queries')
    query_duration = Histogram('rag_query_duration_seconds', 'Query duration')
    query_documents = Histogram('rag_query_documents_retrieved', 'Documents retrieved')
    query_citations = Histogram('rag_query_citations_count', 'Citations count')
    query_errors = Counter('rag_query_errors_total', 'Query errors')
    query_empty = Counter('rag_query_empty_results_total', 'Empty results')

    # Quality metrics
    query_dao_filter = Counter('rag_query_dao_filter_applied', 'DAO filter applied', ['dao_id'])

Використання: - В `ingest_pipeline.py`: після успішного ingest - В `query_pipeline.py`: після кожного query

### 2.2. Router

Файл: `metrics.py` (в корені Router)

    from prometheus_client import Counter, Histogram

    rag_query_total = Counter('router_rag_query_total', 'Total RAG queries')
    rag_query_duration = Histogram('router_rag_query_duration_seconds', 'RAG query duration')
    rag_query_memory_used = Counter('router_rag_query_memory_used', 'Memory used in RAG queries')
    rag_query_rag_used = Counter('router_rag_query_rag_used', 'RAG used in queries')
    rag_query_fallback = Counter('router_rag_query_fallback_total', 'Fallback to Memory only')

Використання: - В `router_app.py`: в `_handle_rag_query()`

## 3. Dashboard (Grafana)

### 3.1. Panels

RAG Service: 1. Ingest Rate - `rate(rag_ingest_total[5m])` 2. Ingest Duration - `histogram_quantile(0.95, rag_ingest_duration_seconds)` 3. Documents Indexed - `sum(rag_ingest_documents_indexed)` 4. Query Rate - `rate(rag_query_total[5m])` 5. Query Duration - `histogram_quantile(0.95, rag_query_duration_seconds)` 6. Documents Retrieved - `avg(rag_query_documents_retrieved)` 7. Citations Count - `avg(rag_query_citations_count)` 8. Empty Results Rate - `rate(rag_query_empty_results_total[5m]) / rate(rag_query_total[5m])`

Router (RAG Query): 1. RAG Query Rate - `rate(router_rag_query_total[5m])` 2. RAG Query Duration - `histogram_quantile(0.95, router_rag_query_duration_seconds)` 3. Memory Usage Rate - `rate(router_rag_query_memory_used[5m]) / rate(router_rag_query_total[5m])` 4. RAG Usage Rate - `rate(router_rag_query_rag_used[5m]) / rate(router_rag_query_total[5m])` 5. Fallback Rate - `rate(router_rag_query_fallback_total[5m]) / rate(router_rag_query_total[5m])`

Memory Service: 1. Context Fetch Rate - `rate(memory_context_fetch_total[5m])` 2. Context Fetch Duration - `histogram_quantile(0.95, memory_context_fetch_duration_seconds)` 3. Average Facts Count - `avg(memory_context_facts_count)` 4. Average Events Count - `avg(memory_context_events_count)`

### 3.2. Alerts

- High Error Rate: `rate(rag_query_errors_total[5m]) > 0.1`
- Slow Queries: `histogram_quantile(0.95, rag_query_duration_seconds) > 10`
- High Fallback Rate: `rate(router_rag_query_fallback_total[5m]) / rate(router_rag_query_total[5m]) > 0.2`
- Empty Results: `rate(rag_query_empty_results_total[5m]) / rate(rag_query_total[5m]) > 0.3`

## 4. Реалізація (мінімальна)

### 4.1. Додати Prometheus Client

RAG Service:

    pip install prometheus-client

Router:

    pip install prometheus-client

### 4.2. Expose Metrics Endpoint

RAG Service:

    # app/main.py
    from prometheus_client import generate_latest, CONTENT_TYPE_LATEST
    from fastapi.responses import Response

    @app.get("/metrics")
    async def metrics():
        return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)

Router:

    # http_api.py
    @app.get("/metrics")
    async def metrics():
        return Response(content=generate_latest(), media_type=CONTENT_TYPE_LATEST)

### 4.3. Docker Compose для Prometheus + Grafana

    prometheus:
      image: prom/prometheus
      volumes:
        - ./prometheus.yml:/etc/prometheus/prometheus.yml
      ports:
        - "9090:9090"

    grafana:
      image: grafana/grafana
      ports:
        - "3000:3000"
      environment:
        - GF_SECURITY_ADMIN_PASSWORD=admin

## 5. Наступні кроки

1. Додати `prometheus-client` в requirements
2. Створити `metrics.py` в RAG Service та Router
3. Додати `/metrics` endpoints
4. Налаштувати Prometheus scraping
5. Створити Grafana dashboard
6. Налаштувати alerts

## 6. Корисні запити для аналізу

Hit Rate (кількість успішних запитів з результатами):

    (rag_query_total - rag_query_empty_results_total) / rag_query_total

Average Documents per Query:

    avg(rag_query_documents_retrieved)

DAO Distribution:

    sum by (dao_id) (rag_query_dao_filter_applied)

Token Usage:

    avg(router_rag_query_prompt_tokens_estimated)