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

# 📊 Metrics Service

> A lightweight FastAPI microservice for user registration analytics and statistics

[![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 from StarRocks database, offering flexible analytics and insights into user growth patterns.

## ✨ Features

### 📊 User Registration Statistics APIs
- **Date Range Query** - Query registration data for specific date ranges
- **Recent N Days Query** - Get registration data for the last N days
- **Start Date + Days Query** - Query N days starting from a specified date
- **Statistics Summary** - Get comprehensive statistics and analytics
- **POST Method Support** - JSON request body support for complex queries

### 🗄️ Database Integration
- **StarRocks Database Connection**
  - Host: `freeleaps-starrocks-cluster-fe-service.freeleaps-data-platform.svc`
  - Port: `9030`
  - Database: `freeleaps`
  - Table: `dws_daily_registered_users`

### 🔧 Technical Features
- **Data Models**: Pydantic validation for data integrity
- **Connection Management**: Automatic database connection and disconnection
- **Error Handling**: Comprehensive exception handling with user-friendly error messages
- **Logging**: Structured logging using Loguru
- **API Documentation**: Auto-generated Swagger/OpenAPI documentation

## 📁 Project Structure

```
metrics/
├── backend/                    # Business logic layer
│   ├── infra/                 # Infrastructure components
│   │   └── database_client.py
│   ├── models/                # Data models
│   │   └── user_registration_models.py
│   └── services/              # Business services
│       └── registration_analytics_service.py
├── webapi/                    # API layer
│   ├── routes/                # API endpoints
│   │   └── registration_metrics.py
│   ├── config/                # Configuration
│   │   └── app_settings.py
│   ├── bootstrap/             # App initialization
│   │   └── app_factory.py
│   └── main.py               # FastAPI app entry point
├── common/                   # Shared utilities
├── requirements.txt          # Dependencies
├── Dockerfile               # Container config
├── local.env               # Environment variables
└── README.md              # Documentation
```

## 🚀 Quick Start

### Prerequisites
- Python 3.12+ or Docker
- Access to StarRocks database

### 🐍 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
docker run --rm -p 8009:8009 metrics:latest
```

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

## 📊 API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/metrics/daily-registered-users` | GET/POST | Query registration data by date range |
| `/api/metrics/recent-registered-users` | GET | Get recent N days data |
| `/api/metrics/registered-users-by-days` | GET | Query N days from start date |
| `/api/metrics/registration-summary` | GET | Get statistical summary |

### Example Requests

```bash
# Get last 7 days
curl "http://localhost:8009/api/metrics/recent-registered-users?days=7"

# Get date range
curl "http://localhost:8009/api/metrics/daily-registered-users?start_date=2024-09-10&end_date=2024-09-20"

# Get summary statistics
curl "http://localhost:8009/api/metrics/registration-summary?start_date=2024-09-10&end_date=2024-09-20"
```

### Parameters
- `start_date` / `end_date`: Date in `YYYY-MM-DD` format
- `days`: Number of days (max: 365)
- `product_id`: Product identifier (default: "freeleaps")

## 📈 Response Format

### Standard Response
```json
{
  "dates": ["2024-09-10", "2024-09-11", "2024-09-12"],
  "counts": [39, 38, 31],
  "total_registrations": 108,
  "query_period": "2024-09-10 to 2024-09-12"
}
```

### Summary Response
```json
{
  "total_registrations": 282,
  "average_daily": 25.64,
  "max_daily": 39,
  "min_daily": 8,
  "days_with_registrations": 10,
  "total_days": 11
}
```

## 🧪 Testing

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

# Test recent registrations
curl "http://localhost:8009/api/metrics/recent-registered-users?days=7"
```

### Interactive Testing
Visit `http://localhost:8009/docs` for the Swagger UI interface where you can test all endpoints directly.

## ⚙️ 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
```

> 💡 **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`
- Max query range: 365 days
- Default `product_id`: "freeleaps"
- Requires StarRocks database access

## 🐛 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.