PyObservability 1.0.0__py3-none-any.whl → 1.1.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,5 +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

@@ -5,12 +5,38 @@ import socket
 from typing import Any, Dict, List
 
 import yaml
-from pydantic import BaseModel, Field, FilePath, HttpUrl, PositiveInt
+from pydantic import BaseModel, Field, FilePath, HttpUrl, PositiveInt, DirectoryPath
 from pydantic.aliases import AliasChoices
 from pydantic_settings import BaseSettings
 
+from pyobservability.config import enums
 
-def detailed_log_config() -> Dict[str, Any]:
+
+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",
+            "formatter": "default",
+            "filename": filename,
+            "mode": "a",
+        }
+    else:
+        log_handler = {
+            "class": "logging.StreamHandler",
+            "formatter": "default",
+            "stream": "ext://sys.stdout",
+        }
+    level = "DEBUG" if debug else "INFO"
     return {
         "version": 1,
         "disable_existing_loggers": False,
@@ -20,19 +46,13 @@ def detailed_log_config() -> Dict[str, Any]:
                 "datefmt": "%b-%d-%Y %I:%M:%S %p",
             }
         },
-        "handlers": {
-            "default": {
-                "class": "logging.StreamHandler",
-                "formatter": "default",
-                "stream": "ext://sys.stdout",
-            }
-        },
+        "handlers": {"default": log_handler},
         "loggers": {
-            "uvicorn": {"handlers": ["default"], "level": "INFO"},
-            "uvicorn.error": {"handlers": ["default"], "level": "INFO", "propagate": False},
-            "uvicorn.access": {"handlers": ["default"], "level": "INFO", "propagate": False},
+            "uvicorn": {"handlers": ["default"], "level": level},
+            "uvicorn.error": {"handlers": ["default"], "level": level, "propagate": False},
+            "uvicorn.access": {"handlers": ["default"], "level": level, "propagate": False},
         },
-        "root": {"handlers": ["default"], "level": "INFO"},
+        "root": {"handlers": ["default"], "level": level},
     }
 
 
@@ -52,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
@@ -89,6 +122,9 @@ class EnvConfig(PydanticEnvConfig):
     targets: List[MonitorTarget] = Field(..., validation_alias=alias_choices("TARGETS"))
     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"))
@@ -99,6 +135,7 @@ class EnvConfig(PydanticEnvConfig):
 
         env_prefix = ""
         extra = "forbid"
+        hide_input_in_errors = True
 
     @classmethod
     def from_env_file(cls, filename: pathlib.Path) -> "EnvConfig":

pyobservability/main.py

@@ -1,6 +1,9 @@
 import logging
+import os
 import pathlib
 import warnings
+from datetime import datetime
+from typing import Dict
 
 import uiauth
 import uvicorn
@@ -32,23 +35,47 @@ 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__}
     )
 
 
-def include_routes():
+async def health() -> Dict[str, str]:
+    """Health check endpoint.
+
+    Returns:
+        dict:
+        Health status.
+    """
+    return {"status": "ok"}
+
+
+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,
+            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,
@@ -75,7 +102,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}
@@ -85,6 +113,15 @@ def start(**kwargs):
         port=settings.env.port,
         app=PyObservability,
     )
+    if settings.env.log:
+        if settings.env.log == enums.Log.stdout:
+            uvicorn_args["log_config"] = settings.detailed_log_config(debug=settings.env.debug)
+        else:
+            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"] = (
             settings.env.log_config if isinstance(settings.env.log_config, dict) else str(settings.env.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:

pyobservability/transport.py

@@ -10,13 +10,24 @@ from pyobservability.monitor import Monitor
 LOGGER = logging.getLogger("uvicorn.default")
 
 
-async def _forward_metrics(websocket: WebSocket, q: asyncio.Queue):
+async def _forward_metrics(websocket: WebSocket, q: asyncio.Queue) -> None:
+    """Forward metrics from the monitor's queue to the websocket.
+
+    Args:
+        websocket: FastAPI WebSocket connection.
+        q: asyncio.Queue to receive metrics from the monitor.
+    """
     while True:
         payload = await q.get()
         await websocket.send_json(payload)
 
 
-async def websocket_endpoint(websocket: WebSocket):
+async def websocket_endpoint(websocket: WebSocket) -> None:
+    """Websocket endpoint to handle observability data streaming.
+
+    Args:
+        websocket: FastAPI WebSocket connection.
+    """
     await websocket.accept()
 
     monitor: Monitor | None = None

pyobservability/version.py

@@ -1 +1 @@
-__version__ = "1.0.0"
+__version__ = "1.1.0"

{pyobservability-1.0.0.dist-info → pyobservability-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyObservability
-Version: 1.0.0
+Version: 1.1.0
 Summary: Lightweight OS-agnostic observability UI for PyNinja
 Author-email: Vignesh Rao <svignesh1793@gmail.com>
 License: MIT License
@@ -29,11 +29,11 @@ Project-URL: Homepage, https://github.com/thevickypedia/PyObservability
 Project-URL: Docs, https://thevickypedia.github.io/PyObservability
 Project-URL: Source, https://github.com/thevickypedia/PyObservability
 Project-URL: Bug Tracker, https://github.com/thevickypedia/PyObservability/issues
-Project-URL: Release Notes, https://github.com/thevickypedia/PyObservability/blob/main/release_notes.rst
+Project-URL: Release Notes, https://github.com/thevickypedia/PyObservability/blob/main/release_notes.md
 Keywords: PyObservability,observability,system-monitor,PyNinja
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
@@ -50,10 +50,7 @@ Requires-Dist: pydantic-settings==2.12.*
 Requires-Dist: python-dotenv==1.2.*
 Requires-Dist: uvicorn[standard]==0.38.*
 Provides-Extra: dev
-Requires-Dist: sphinx==5.1.1; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: recommonmark; extra == "dev"
-Requires-Dist: gitverse; extra == "dev"
 Dynamic: license-file
 
 # PyObservability
@@ -69,6 +66,7 @@ Dynamic: license-file
 [![pypi][label-actions-pypi]][gha_pypi]
 [![notes][label-actions-notes]][gha_notes]
 [![release][label-actions-release]][gha_release]
+[![docker][label-actions-docker]][gha_docker]
 
 [![Pypi][label-pypi]][pypi]
 [![Pypi-format][label-pypi-format]][pypi-files]
@@ -102,13 +100,25 @@ pyobservability start
 
 > Use `pyobservability --help` for usage instructions.
 
+**Containerized Deployment**
+```shell
+docker pull thevickypedia/pyobservability:latest
+
+docker run \
+    --name observability \
+    -p 8080:80 \
+    -v /home/user/config:/config \
+    --restart=no \
+    thevickypedia/pyobservability
+```
+
 ## Environment Variables
 
 <details>
 <summary><strong>Sourcing environment variables from an env file</strong></summary>
 
 > _By default, `PyObservability` will look for a `.env` file in the current working directory._
-> _Other file options are supported with a custom kwarg or env var `env_file` pointing to the filepath._
+> _Other file options (like JSON and YAML) are supported with a custom kwarg or env var `env_file` pointing to the filepath._
 </details>
 
 **Mandatory**
@@ -142,22 +152,14 @@ Licensed under the [MIT License][license]
 [label-pypi-status]: https://img.shields.io/pypi/status/PyObservability
 [label-actions-notes]: https://github.com/thevickypedia/PyObservability/actions/workflows/notes.yml/badge.svg
 [label-actions-release]: https://github.com/thevickypedia/PyObservability/actions/workflows/release.yml/badge.svg
+[label-actions-docker]: https://github.com/thevickypedia/PyObservability/actions/workflows/docker.yml/badge.svg
 
 [3.11]: https://docs.python.org/3/whatsnew/3.11.html
 [virtual environment]: https://docs.python.org/3/tutorial/venv.html
-[release-notes]: https://github.com/thevickypedia/PyObservability/blob/main/release_notes.rst
 [gha_pypi]: https://github.com/thevickypedia/PyObservability/actions/workflows/python-publish.yml
 [gha_notes]: https://github.com/thevickypedia/PyObservability/actions/workflows/notes.yml
 [gha_release]: https://github.com/thevickypedia/PyObservability/actions/workflows/release.yml
-[google-docs]: https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings
-[pep8]: https://www.python.org/dev/peps/pep-0008/
-[isort]: https://pycqa.github.io/isort/
-[sphinx]: https://www.sphinx-doc.org/en/master/man/sphinx-autogen.html
+[gha_docker]: https://github.com/thevickypedia/PyObservability/actions/workflows/docker.yml
 [pypi]: https://pypi.org/project/PyObservability
 [pypi-files]: https://pypi.org/project/PyObservability/#files
-[pypi-repo]: https://packaging.python.org/tutorials/packaging-projects/
 [license]: https://github.com/thevickypedia/PyObservability/blob/main/LICENSE
-[runbook]: https://thevickypedia.github.io/PyObservability/
-[samples]: https://github.com/thevickypedia/PyObservability/tree/main/samples
-[PyUdisk]: https://github.com/thevickypedia/PyUdisk
-[PyArchitecture]: https://github.com/thevickypedia/PyArchitecture

pyobservability-1.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pyobservability/__init__.py,sha256=yVBLyTohBiBKp0Otyl04IggPh8mhg3Er25u6eFyxMto,2618
+pyobservability/main.py,sha256=WC57zDTv588aNPViV352WcWmJxURF5EvY9X26roNuW0,4316
+pyobservability/monitor.py,sha256=Y38zDJFPDbQqz_2jQcNmJBnRpeobC_SV2uhN-13e9RU,7591
+pyobservability/transport.py,sha256=zHLAodX20bKkPOuacKjzv1Dqj3JbNAB75o1ABwzum0U,2534
+pyobservability/version.py,sha256=LGVQyDsWifdACo7qztwb8RWWHds1E7uQ-ZqD8SAjyw4,22
+pyobservability/config/enums.py,sha256=EhvD9kB5EMW3ARxr5KmISmf-rP3D4IKqOIjw6Tb8SB8,294
+pyobservability/config/settings.py,sha256=adeTQCV5_bf_8zBggkdIXniyXsbqJYAAUupB2tvOVNI,5820
+pyobservability/static/app.js,sha256=6hjFy2jt4ndYJUI1DZT08CpuxHyWj9iSAZ2vxaTqH2A,20664
+pyobservability/static/styles.css,sha256=dnYSXNeXd6Ohu4h8sJCO87vzPbkYcw9XVGGwB8IJbxw,4703
+pyobservability/templates/index.html,sha256=2aQdb0QlDY5Hboev-_lJPlpnGxiC6h3fp0FlvL72S9k,5227
+pyobservability-1.1.0.dist-info/licenses/LICENSE,sha256=_sOIKJWdD2o1WwwDIwYB2qTP2nlSWqT5Tyg9jr1Xa4w,1070
+pyobservability-1.1.0.dist-info/METADATA,sha256=KZoudD6ox48fOOmhPEW7WXPgYO26bps3C9kq68wkFy0,6539
+pyobservability-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyobservability-1.1.0.dist-info/entry_points.txt,sha256=DSGIr_VA8Tb3FYa2iNUYpf55eAvuFCAoInNS4ngXaME,57
+pyobservability-1.1.0.dist-info/top_level.txt,sha256=p20T0EmihDYW1uMintRXr7X9bg3XWYKyoSbBHOVC1xI,16
+pyobservability-1.1.0.dist-info/RECORD,,

pyobservability-1.0.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-pyobservability/__init__.py,sha256=rr4udGMbbNPl3yo7l8R3FUUVVahBtYVaW6vSWWgXlv0,2617
-pyobservability/main.py,sha256=Ty0bS7ZWyKXuo-xuKoFQESvT-B-19W04d_Nk0KveNtg,3004
-pyobservability/monitor.py,sha256=4Xd8k7gcOmHM-WvQpgFiDVGtzMu_RpFPZXPPoz4GoA4,6224
-pyobservability/transport.py,sha256=FyzJAMZPn7JUZIGgxnSw3on1K6T4ciZE1EuGdAcxt_w,2188
-pyobservability/version.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
-pyobservability/config/enums.py,sha256=iMIOpa8LYSszkPIYBhupX--KrEXVTTsBurinpAxLvMA,86
-pyobservability/config/settings.py,sha256=BjTZnkGS1pZKbN3Fq_5HQX8C6oEjWn_gVJLXcZZ6EWE,4853
-pyobservability/static/app.js,sha256=6hjFy2jt4ndYJUI1DZT08CpuxHyWj9iSAZ2vxaTqH2A,20664
-pyobservability/static/styles.css,sha256=dnYSXNeXd6Ohu4h8sJCO87vzPbkYcw9XVGGwB8IJbxw,4703
-pyobservability/templates/index.html,sha256=2aQdb0QlDY5Hboev-_lJPlpnGxiC6h3fp0FlvL72S9k,5227
-pyobservability-1.0.0.dist-info/licenses/LICENSE,sha256=_sOIKJWdD2o1WwwDIwYB2qTP2nlSWqT5Tyg9jr1Xa4w,1070
-pyobservability-1.0.0.dist-info/METADATA,sha256=4Wj2FH4KYhsDbEntXxnMginYE9QR9AluZyYLMHvwhbg,6822
-pyobservability-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyobservability-1.0.0.dist-info/entry_points.txt,sha256=DSGIr_VA8Tb3FYa2iNUYpf55eAvuFCAoInNS4ngXaME,57
-pyobservability-1.0.0.dist-info/top_level.txt,sha256=p20T0EmihDYW1uMintRXr7X9bg3XWYKyoSbBHOVC1xI,16
-pyobservability-1.0.0.dist-info/RECORD,,