freeleaps-service-hub/apps/metrics

📊 Metrics Service

A lightweight FastAPI microservice for user registration analytics and statistics

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

# 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

# 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

# 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

{
  "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

{
  "total_registrations": 282,
  "average_daily": 25.64,
  "max_daily": 39,
  "min_daily": 8,
  "days_with_registrations": 10,
  "total_days": 11
}

🧪 Testing

Quick Test

# 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

# 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

# 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

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