freeleaps-service-hub/apps/metrics

📊 Metrics Service

A lightweight FastAPI microservice for user registration analytics and metrics

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

# 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 (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:

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

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

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

# Prometheus
PROMETHEUS_ENDPOINT=http://localhost:9090

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