freeleaps-service-hub/apps/metrics/README.md

# 📊 Metrics Service

> A lightweight FastAPI microservice for user registration analytics and metrics

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.114+-green.svg)](https://fastapi.tiangolo.com)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://docker.com)

The Metrics service provides real-time APIs for querying user registration data (via StarRocks) and querying monitoring metrics (via Prometheus).

## ✨ Features

### 📊 Registration Analytics (StarRocks)
- Date Range Query (start_date ~ end_date)
- Typed responses with Pydantic models

### 📈 Prometheus Metrics
- Predefined PromQL metrics per product
- Time-range queries and metric info discovery

### 🔧 Technical Features
- Data Models: Pydantic v2
- Async HTTP and robust error handling
- Structured logging
- Auto-generated Swagger/OpenAPI docs

## 📁 Project Structure

```
metrics/
├── backend/                    # Business logic layer
│   ├── infra/                 # Infrastructure components
│   │   └── external_service/
│   │       ├── prometheus_client.py
│   │       └── starrocks_client.py
│   ├── models/                # Data models
│   │   └── user_registration_models.py
│   └── services/              # Business services
│       ├── prometheus_metrics_service.py
│       └── registration_analytics_service.py
├── webapi/                    # API layer
│   ├── routes/                # API endpoints
│   │   ├── metrics/           # Aggregated routers (prefix: /api/metrics)
│   │   ├── prometheus_metrics/
│   │   │   ├── __init__.py
│   │   │   ├── available_metrics.py
│   │   │   ├── metric_info.py
│   │   │   └── metrics_query.py
│   │   └── starrocks_metrics/
│   │       ├── __init__.py
│   │       ├── available_metrics.py
│   │       ├── metric_info.py
│   │       └── metrics_query.py
│   ├── bootstrap/
│   │   └── application.py
│   └── main.py
├── common/
├── requirements.txt
├── Dockerfile
├── local.env
└── README.md
```

## 🚀 Quick Start

### Prerequisites
- Python 3.12+ or Docker
- Access to StarRocks database (for registration analytics)
- Access to Prometheus (for monitoring metrics)

### 🐍 Python Setup

```bash
# 1. Install dependencies
pip install -r requirements.txt

# 2. Start the service
python3 -m uvicorn webapi.main:app --host 0.0.0.0 --port 8009 --reload
```

### 🐳 Docker Setup

```bash
# 1. Build image
docker build -t metrics:latest .

# 2. Run container (env from baked local.env)
docker run --rm -p 8009:8009 metrics:latest

# Alternatively: run with a custom env file
# (this overrides envs copied into the image)
docker run --rm -p 8009:8009 --env-file local.env metrics:latest
```

### 📖 Access Documentation
Visit `http://localhost:8009/docs` for interactive API documentation.

## 📊 API Endpoints

All endpoints are exposed under the API base prefix `/api/metrics`.

### StarRocks (Registration Analytics)
- POST `/api/metrics/starrocks/dru_query` — Query daily registered users time series for a date range
- GET `/api/metrics/starrocks/product/{product_id}/available-metrics` — List available StarRocks-backed metrics for the product
- GET `/api/metrics/starrocks/product/{product_id}/metric/{metric_name}/info` — Get metric info for the product

Example request:
```bash
curl -X POST "http://localhost:8009/api/metrics/starrocks/dru_query" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "freeleaps",
    "start_date": "2024-09-10",
    "end_date": "2024-09-20"
  }'
```

### Prometheus
- POST `/api/metrics/prometheus/metrics_query` — Query metric time series by product/metric
- GET `/api/metrics/prometheus/product/{product_id}/available-metrics` — List available metrics for product
- GET `/api/metrics/prometheus/product/{product_id}/metric/{metric_name}/info` — Get metric info

## 🧪 Testing

```bash
# Health check
curl http://localhost:8009/
```

## ⚙️ Configuration

### Environment Variables
```bash
# Server Configuration
SERVICE_API_ACCESS_HOST=0.0.0.0
SERVICE_API_ACCESS_PORT=8009

# StarRocks Database
STARROCKS_HOST=freeleaps-starrocks-cluster-fe-service.freeleaps-data-platform.svc
STARROCKS_PORT=9030
STARROCKS_USER=root
STARROCKS_PASSWORD=
STARROCKS_DATABASE=freeleaps

# Logging
LOG_BASE_PATH=./logs
BACKEND_LOG_FILE_NAME=metrics
APPLICATION_ACTIVITY_LOG=metrics-activity

# Prometheus
PROMETHEUS_ENDPOINT=http://localhost:9090
```

> Tip: Copy `local.env` to `.env` and modify as needed for your environment.

### 🐳 Docker Deployment

```bash
# Build and run
docker build -t metrics:latest .
docker run --rm -p 8009:8009 metrics:latest

# Run with custom environment
docker run --rm -p 8009:8009 --env-file local.env metrics:latest

# Run in background
docker run -d --name metrics-service -p 8009:8009 metrics:latest
```

**Image Details:**
- Base: Python 3.12-slim
- Port: 8009
- Working Dir: `/app`

## 🔧 Development

```bash
# Setup development environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run with auto-reload
python -m uvicorn webapi.main:app --reload
```

## 📝 API Documentation
- Swagger UI: `http://localhost:8009/docs`
- ReDoc: `http://localhost:8009/redoc`
- OpenAPI JSON: `http://localhost:8009/openapi.json`

## ⚠️ Important Notes
- Date format: `YYYY-MM-DD` (single-digit month/day also accepted by API)
- Default `product_id`: "freeleaps"
- Requires StarRocks database access and/or Prometheus endpoint

## 🐛 Troubleshooting
| Issue | Solution |
|-------|----------|
| Port in use | `docker stop $(docker ps -q --filter ancestor=metrics:latest)` |
| Import errors | Check dependencies: `pip install -r requirements.txt` |
| DB connection | Verify StarRocks cluster accessibility |
| Container issues | Check logs: `docker logs <container_id>` |

## 📄 License

Part of the Freeleaps platform.