feat: application refactor with prometheus

feat: application refactor with prometheus

Author: milsman2

.github/workflows/ci-cd.yaml

@@ -13,20 +13,20 @@ on:
 
 jobs:
   cache:
-    uses: ./.github/workflows/cache-uv-build.yaml
+    uses: milsman2/python-app-template/.github/workflows/cache-uv-build.yaml@main
 
   lint:
-    uses: ./.github/workflows/ruff.yaml
+    uses: milsman2/python-app-template/.github/workflows/ruff.yaml@main
     needs: cache
 
   test:
     needs: [lint, cache]
-    uses: ./.github/workflows/pytest.yaml
+    uses: milsman2/python-app-template/.github/workflows/pytest.yaml@main
 
   docker:
     if: github.event_name == 'push'
     needs: test
-    uses: ./.github/workflows/docker-build-and-scan.yaml
+    uses: milsman2/python-app-template/.github/workflows/docker-build-and-scan.yaml@main
     with:
       DOCKER_PATH_CONTEXT: .
       DOCKER_BUILD_DOCKERFILE: ./Dockerfile

.github/workflows/docker-build-and-scan.yaml

@@ -46,7 +46,7 @@ jobs:
           tags: ${{  inputs.DOCKER_TAGS }}
       - name: Run Trivy vulnerability scanner (remote)
         if: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') }}
-        uses: aquasecurity/trivy-action@0.33.1
+        uses: aquasecurity/trivy-action@0.34.0
         with:
           image-ref: docker.io/${{ inputs.DOCKER_TAGS }}
           format: 'table'

.github/workflows/pytest.yaml

@@ -14,7 +14,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-
       - name: Restore uv caches
         id: cache-restore
         uses: actions/cache/restore@v5

.github/workflows/ruff.yaml

@@ -15,7 +15,6 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
-
       - name: Restore global uv cache
         id: cache-restore
         uses: actions/cache/restore@v5

pyproject.toml

@@ -5,12 +5,14 @@ description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
+    "apscheduler>=3.11.2",
     "black>=26.1.0",
     "coverage>=7.13.2",
     "httpx>=0.28.1",
     "isort>=7.0.0",
     "loguru>=0.7.3",
     "pathlib>=1.0.1",
+    "prometheus-client>=0.24.1",
     "pydantic>=2.12.5",
     "pydantic-extra-types>=2.11.0",
     "pydantic-settings>=2.12.0",

src/sample_python_app/__init__.py

@@ -1 +1,5 @@
 """Sample Python app package initialization."""
+
+from sample_python_app.main import run_app
+
+__all__ = ["run_app"]

src/sample_python_app/app/__init__.py

@@ -0,0 +1,11 @@
+"""App module for the sample Python application.
+
+This module contains the main components for running the application, including
+the metrics server, scheduler, and the main application runner.
+"""
+
+from sample_python_app.app.lifecycle import start_metrics_server
+from sample_python_app.app.runner import fetch_astro_data
+from sample_python_app.app.scheduler import start_scheduler
+
+__all__ = ["start_metrics_server", "start_scheduler", "fetch_astro_data"]

src/sample_python_app/app/lifecycle.py

@@ -0,0 +1,31 @@
+"""Lifecycle management for metrics server.
+
+Handles Prometheus metrics server startup and port checks.
+"""
+
+import socket
+
+from prometheus_client import start_http_server
+
+from sample_python_app.core.logging import setup_logger
+
+logger = setup_logger("normal")
+
+
+def start_metrics_server(port: int) -> None:
+    """Start the Prometheus metrics server on the specified port."""
+    if _port_in_use(port):
+        logger.error("Port %s already in use; metrics disabled", port)
+        return
+
+    logger.info(f"Starting Prometheus metrics on 0.0.0.0:{port}")
+    start_http_server(port, addr="0.0.0.0")
+
+
+def _port_in_use(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        try:
+            sock.bind(("localhost", port))
+        except OSError:
+            return True
+    return False

src/sample_python_app/app/runner.py

@@ -0,0 +1,79 @@
+"""Runner module for the sample Python app.
+
+Handles fetching, validation, and display of astronomical data.
+"""
+
+# app/runner.py
+import json
+import time
+
+import httpx
+from pydantic import ValidationError
+
+from sample_python_app.core import (
+    FETCH_COUNTER,
+    FETCH_DURATION,
+    FETCH_ERRORS,
+    display_astronomical_data,
+    setup_logger,
+    weather_settings,
+)
+from sample_python_app.exceptions import AppError
+from sample_python_app.services import fetch_astronomical_data_from_api
+
+logger = setup_logger("normal")
+
+
+def fetch_astro_data(*, exit_on_error: bool = True) -> None:
+    """Fetch and display astronomical data once, with error handling."""
+    lat = weather_settings.LOCATION.latitude
+    lon = weather_settings.LOCATION.longitude
+    logger.info(f"Using latitude={lat} longitude={lon}")
+
+    start = time.time()
+
+    try:
+        astro = fetch_astronomical_data_from_api(lat, lon)
+        FETCH_COUNTER.inc()
+    except httpx.HTTPStatusError as exc:
+        _handle_fetch_error(exc, exit_on_error)
+        return
+    except httpx.RequestError as exc:
+        _handle_fetch_error(exc, exit_on_error)
+        return
+    except ValidationError as exc:
+        _handle_fetch_error(exc, exit_on_error)
+        return
+    except json.JSONDecodeError as exc:
+        _handle_fetch_error(exc, exit_on_error)
+        return
+    except AppError as exc:
+        _handle_fetch_error(exc, exit_on_error)
+        return
+    finally:
+        FETCH_DURATION.observe(time.time() - start)
+
+    display_astronomical_data(astro)
+
+
+def _handle_fetch_error(exc: Exception, exit_on_error: bool) -> None:
+    """Handle errors during the fetch operation.
+
+    Log appropriately and update metrics.
+    """
+    FETCH_ERRORS.inc()
+    if isinstance(exc, httpx.HTTPStatusError):
+        logger.error("HTTP status error: %s", exc)
+    elif isinstance(exc, httpx.RequestError):
+        logger.error("Network error: %s", exc)
+    elif isinstance(exc, ValidationError):
+        logger.error("Validation error: %s", exc)
+    elif isinstance(exc, json.JSONDecodeError):
+        logger.error("JSON decode error: %s", exc)
+    else:
+        logger.exception("Unexpected error")
+
+    if exit_on_error:
+        raise SystemExit(1) from exc
+
+    raise AppError(str(exc)) from exc

src/sample_python_app/app/scheduler.py

@@ -0,0 +1,39 @@
+"""Scheduler module for periodic astronomical data fetch.
+
+Initializes and runs the APScheduler job every 24 hours.
+"""
+
+from datetime import datetime
+
+from apscheduler.schedulers.blocking import BlockingScheduler
+
+from sample_python_app.app.runner import fetch_astro_data
+from sample_python_app.core.logging import setup_logger
+
+logger = setup_logger("normal")
+
+
+def start_scheduler(test_mode: bool = False) -> None:
+    """Start the scheduler to run the astronomical data fetch every 24 hours.
+
+    In test_mode, run the scheduled job once and do not block.
+    """
+    scheduler = BlockingScheduler()
+    scheduler.add_job(
+        fetch_astro_data,
+        trigger="interval",
+        hours=24,
+        next_run_time=datetime.now(),
+    )
+    logger.info("Scheduled astronomical fetch every 24 hours")
+    if test_mode:
+        # Run the job once for testing, do not block
+        job = scheduler.get_jobs()[0]
+        job.func()
+        logger.info("Ran scheduled job once in test mode")
+        return
+    try:
+        scheduler.start()
+    except (KeyboardInterrupt, SystemExit):
+        logger.info("Scheduler stopped")
+        scheduler.shutdown()