PyObservability 1.0.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

pyobservability/__init__.py

@@ -32,7 +32,7 @@ def _cli() -> None:
     )
     args = [arg.lower() for arg in sys.argv[1:]]
     try:
-        assert len(args) > 1
+        assert len(args) >= 1
     except (IndexError, AttributeError, AssertionError):
         print(f"Cannot proceed without a valid arbitrary command. Please choose from {choices}")
         exit(1)

pyobservability/config/enums.py

@@ -2,10 +2,23 @@ from enum import StrEnum
 
 
 class APIEndpoints(StrEnum):
+    """API endpoints for all the routes.
+
+    >>> APIEndpoints
+
+    """
+
+    health = "/health"
     root = "/"
     ws = "/ws"
 
 
 class Log(StrEnum):
+    """Log output options.
+
+    >>> Log
+
+    """
+
     file = "file"
     stdout = "stdout"

pyobservability/config/settings.py

@@ -13,6 +13,16 @@ from pyobservability.config import enums
 
 
 def detailed_log_config(filename: str | None = None, debug: bool = False) -> Dict[str, Any]:
+    """Generate a detailed logging configuration.
+
+    Args:
+        filename: Optional log file name. If None, logs to stdout.
+        debug: If True, sets log level to DEBUG, else INFO.
+
+    Returns:
+        Dict[str, Any]:
+        Returns the logging configuration dictionary.
+    """
     if filename:
         log_handler = {
             "class": "logging.FileHandler",
@@ -62,11 +72,24 @@ class PydanticEnvConfig(BaseSettings):
         dotenv_settings,
         file_secret_settings,
     ):
-        """Order: dotenv, env, init, secrets files."""
-        return dotenv_settings, env_settings, init_settings, file_secret_settings
+        """Customize the order of settings sources."""
+        # Precedence (last wins):
+        # env < dotenv < file secrets < init
+        return (
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+            init_settings,
+        )
 
 
 class MonitorTarget(BaseModel):
+    """Model representing a monitoring target.
+
+    >>> MonitorTarget
+
+    """
+
     name: str
     base_url: HttpUrl
     apikey: str
@@ -100,17 +123,20 @@ class EnvConfig(PydanticEnvConfig):
     interval: PositiveInt = Field(3, validation_alias=alias_choices("INTERVAL"))
 
     log: enums.Log | None = None
+    logs_path: str = "logs"
     debug: bool = False
     log_config: Dict[str, Any] | FilePath | None = None
 
     username: str | None = Field(None, validation_alias=alias_choices("USERNAME"))
     password: str | None = Field(None, validation_alias=alias_choices("PASSWORD"))
+    timeout: PositiveInt = Field(300, validation_alias=alias_choices("TIMEOUT"))
 
     class Config:
         """Environment variables configuration."""
 
         env_prefix = ""
         extra = "forbid"
+        hide_input_in_errors = True
 
     @classmethod
     def from_env_file(cls, filename: pathlib.Path) -> "EnvConfig":

pyobservability/main.py

@@ -1,8 +1,8 @@
 import logging
-import os
 import pathlib
 import warnings
 from datetime import datetime
+from typing import Dict
 
 import uiauth
 import uvicorn
@@ -34,24 +34,49 @@ async def index(request: Request):
 
     Args:
         request: FastAPI request object.
+
+    Returns:
+        TemplateResponse:
+        Rendered HTML template with targets and version.
     """
-    return templates.TemplateResponse(
-        "index.html", {"request": request, "targets": settings.env.targets, "version": __version__}
-    )
+    args = dict(request=request, targets=settings.env.targets, version=__version__)
+    if settings.env.username and settings.env.password:
+        args["logout"] = uiauth.enums.APIEndpoints.fastapi_logout.value
+    return templates.TemplateResponse("index.html", args)
+
+
+async def health() -> Dict[str, str]:
+    """Health check endpoint.
+
+    Returns:
+        dict:
+        Health status.
+    """
+    return {"status": "ok"}
 
 
-def include_routes():
+def include_routes() -> None:
+    """Include routes in the FastAPI app with or without authentication."""
+    PyObservability.routes.append(
+        APIRoute(
+            path=enums.APIEndpoints.health,
+            endpoint=health,
+            methods=["GET"],
+            include_in_schema=False,
+        ),
+    )
     if all((settings.env.username, settings.env.password)):
         uiauth.protect(
             app=PyObservability,
             username=settings.env.username,
             password=settings.env.password,
+            timeout=settings.env.timeout,
             custom_logger=LOGGER,
             params=[
                 uiauth.Parameters(
                     path=enums.APIEndpoints.root,
                     function=index,
-                    methods=["GET"],
+                    methods=[uiauth.enums.APIMethods.GET],
                 ),
                 uiauth.Parameters(
                     path=enums.APIEndpoints.ws,
@@ -78,7 +103,8 @@ def include_routes():
         )
 
 
-def start(**kwargs):
+def start(**kwargs) -> None:
+    """Start the FastAPI app with Uvicorn server."""
     settings.env = settings.env_loader(**kwargs)
     settings.env.targets = [{k: str(v) for k, v in target.model_dump().items()} for target in settings.env.targets]
     settings.targets_by_url = {t["base_url"]: t for t in settings.env.targets}
@@ -88,13 +114,16 @@ def start(**kwargs):
         port=settings.env.port,
         app=PyObservability,
     )
-    if log := settings.env.log:
-        if log == enums.Log.stdout:
+    if settings.env.log:
+        if settings.env.log == enums.Log.stdout:
             uvicorn_args["log_config"] = settings.detailed_log_config(debug=settings.env.debug)
         else:
-            log_file = datetime.now().strftime(os.path.join("logs", "pyobservability_%d-%m-%Y.log"))
-            os.makedirs("logs", exist_ok=True)
-            uvicorn_args["log_config"] = settings.detailed_log_config(filename=log_file, debug=settings.env.debug)
+            logs_path = pathlib.Path(settings.env.logs_path)
+            log_file = logs_path / f"pyobservability_{datetime.now():%d-%m-%Y}.log"
+            logs_path.mkdir(parents=True, exist_ok=True)
+            uvicorn_args["log_config"] = settings.detailed_log_config(
+                filename=log_file.resolve(), debug=settings.env.debug
+            )
     # log_config will take precedence if both log and log_config are set
     if settings.env.log_config:
         uvicorn_args["log_config"] = (

pyobservability/monitor.py

@@ -3,7 +3,7 @@ import json
 import logging
 from asyncio import CancelledError
 from collections.abc import Generator
-from typing import Any, Dict, List
+from typing import Any, AsyncGenerator, Dict, List
 
 import aiohttp
 
@@ -14,6 +14,15 @@ OBS_PATH = "/observability"
 
 
 def refine_service(service_list: List[Dict[str, Any]]) -> Generator[Dict[str, Dict[str, str]]]:
+    """Refine service stats to only include relevant fields and round CPU values.
+
+    Args:
+        service_list: List of service statistics dictionaries.
+
+    Yields:
+        Dict[str, Dict[str, str]]:
+        Refined service statistics dictionary.
+    """
     for service in service_list:
         service["memory"] = dict(rss=service.get("memory", {}).get("rss"), vms=service.get("memory", {}).get("vms"))
         service["cpu"] = dict(
@@ -24,7 +33,18 @@ def refine_service(service_list: List[Dict[str, Any]]) -> Generator[Dict[str, Di
 
 
 class Monitor:
+    """Monitor class to stream observability data from a target.
+
+    >>> Monitor
+
+    """
+
     def __init__(self, target: Dict[str, str]):
+        """Initialize Monitor with target configuration.
+
+        Args:
+            target: Dictionary containing target configuration with keys 'name', 'base_url', and 'apikey'.
+        """
         self.name = target["name"]
         self.base_url = target["base_url"]
         self.apikey = target["apikey"]
@@ -40,11 +60,22 @@ class Monitor:
     # SUBSCRIBE / UNSUBSCRIBE
     # ------------------------------
     def subscribe(self) -> asyncio.Queue:
+        """Subscribe to the monitor's data stream.
+
+        Returns:
+            asyncio.Queue:
+            Queue to receive streamed data.
+        """
         q = asyncio.Queue(maxsize=10)
         self._ws_subscribers.append(q)
         return q
 
-    def unsubscribe(self, q: asyncio.Queue):
+    def unsubscribe(self, q: asyncio.Queue) -> None:
+        """Unsubscribe from the monitor's data stream.
+
+        Args:
+            q: Queue to be removed from subscribers.
+        """
         if q in self._ws_subscribers:
             self._ws_subscribers.remove(q)
 
@@ -52,6 +83,7 @@ class Monitor:
     # START / STOP
     # ------------------------------
     async def start(self):
+        """Start the monitor's data streaming."""
         if self._task:
             return  # already running
 
@@ -61,6 +93,7 @@ class Monitor:
         self._task = asyncio.create_task(self._stream_target())
 
     async def stop(self):
+        """Stop the monitor's data streaming."""
         self._stop.set()
         if self._task:
             self._task.cancel()
@@ -74,7 +107,8 @@ class Monitor:
             await self.session.close()
             self.session = None
 
-    async def update_flags(self, **kwargs):
+    async def update_flags(self, **kwargs) -> None:
+        """Update monitor flags and restart the stream."""
         for k, v in kwargs.items():
             if k in self.flags:
                 self.flags[k] = v
@@ -82,14 +116,21 @@ class Monitor:
         # restart stream with new params
         await self._restart_stream()
 
-    async def _restart_stream(self):
+    async def _restart_stream(self) -> None:
+        """Restart the monitor's data streaming."""
         await self.stop()
         await self.start()
 
     # ------------------------------
     # FETCH STREAM
     # ------------------------------
-    async def _fetch_stream(self):
+    async def _fetch_stream(self) -> AsyncGenerator[Dict[str, Any], None]:
+        """Fetch the observability data stream from the target.
+
+        Yields:
+            Dict[str, Any]:
+            Parsed observability data.
+        """
         query = f"?interval={settings.env.interval}"
         if self.flags["all_services"]:
             query += "&all_services=true"
@@ -122,7 +163,8 @@ class Monitor:
     # ------------------------------
     # STREAM LOOP
     # ------------------------------
-    async def _stream_target(self):
+    async def _stream_target(self) -> None:
+        """Stream observability data from the target and notify subscribers."""
         errors = {}
         while not self._stop.is_set():
             try: