fastapi-watchtower 1.0.0__tar.gz

fastapi_watchtower-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 HOTSONHONET
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_watchtower-1.0.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: fastapi-watchtower
+Version: 1.0.0
+Summary: Request tracing and visualization for FastAPI applications.
+Author-email: Hotson Honett <hotsonhonet@gmail.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi[all]>=0.135.3
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: requests>=2.33.1
+Requires-Dist: twine>=6.2.0
+Requires-Dist: viztracer>=1.1.1
+Dynamic: license-file
+
+# WatchTower
+
+
+WatchTower is a project-aware FastAPI runtime observability tool that maps requests to user-defined classes and functions, helping developers understand request flow and inspect profiling data without framework noise.
+
+### Requirements
+- Use `async def` endpoints for best tracing accuracy
+- Sync endpoints (`def`) may lead to incomplete or unstable traces
+
+
+### Example usage
+
+```python
+
+
+from fastapi import FastAPI
+from .api.routes import router
+from watchtower import setup_watchtower
+
+app = FastAPI(title="Complex Profiling Demo")
+
+setup_watchtower(
+    app,
+    source_root="examples",
+    output_dir=".watchtower-complex_server",
+    enable_ui=True,
+    ui_dist_dir="frontend/watchtower-ui/dist",
+)
+app.include_router(router)
+
+```
+
+
+### Example of Request Flow animation of a complex server
+
+![Request Flow Animation](assets/request-animation-flow.gif)

fastapi_watchtower-1.0.0/README.md

@@ -0,0 +1,36 @@
+# WatchTower
+
+
+WatchTower is a project-aware FastAPI runtime observability tool that maps requests to user-defined classes and functions, helping developers understand request flow and inspect profiling data without framework noise.
+
+### Requirements
+- Use `async def` endpoints for best tracing accuracy
+- Sync endpoints (`def`) may lead to incomplete or unstable traces
+
+
+### Example usage
+
+```python
+
+
+from fastapi import FastAPI
+from .api.routes import router
+from watchtower import setup_watchtower
+
+app = FastAPI(title="Complex Profiling Demo")
+
+setup_watchtower(
+    app,
+    source_root="examples",
+    output_dir=".watchtower-complex_server",
+    enable_ui=True,
+    ui_dist_dir="frontend/watchtower-ui/dist",
+)
+app.include_router(router)
+
+```
+
+
+### Example of Request Flow animation of a complex server
+
+![Request Flow Animation](assets/request-animation-flow.gif)

fastapi_watchtower-1.0.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "fastapi-watchtower"
+version = "1.0.0"
+description = "Request tracing and visualization for FastAPI applications."
+authors = [{name = "Hotson Honett", email = "hotsonhonet@gmail.com"}]
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi[all]>=0.135.3",
+    "numpy>=2.4.4",
+    "requests>=2.33.1",
+    "twine>=6.2.0",
+    "viztracer>=1.1.1",
+]
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

fastapi_watchtower-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastapi_watchtower-1.0.0/src/fastapi_watchtower.egg-info/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: fastapi-watchtower
+Version: 1.0.0
+Summary: Request tracing and visualization for FastAPI applications.
+Author-email: Hotson Honett <hotsonhonet@gmail.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi[all]>=0.135.3
+Requires-Dist: numpy>=2.4.4
+Requires-Dist: requests>=2.33.1
+Requires-Dist: twine>=6.2.0
+Requires-Dist: viztracer>=1.1.1
+Dynamic: license-file
+
+# WatchTower
+
+
+WatchTower is a project-aware FastAPI runtime observability tool that maps requests to user-defined classes and functions, helping developers understand request flow and inspect profiling data without framework noise.
+
+### Requirements
+- Use `async def` endpoints for best tracing accuracy
+- Sync endpoints (`def`) may lead to incomplete or unstable traces
+
+
+### Example usage
+
+```python
+
+
+from fastapi import FastAPI
+from .api.routes import router
+from watchtower import setup_watchtower
+
+app = FastAPI(title="Complex Profiling Demo")
+
+setup_watchtower(
+    app,
+    source_root="examples",
+    output_dir=".watchtower-complex_server",
+    enable_ui=True,
+    ui_dist_dir="frontend/watchtower-ui/dist",
+)
+app.include_router(router)
+
+```
+
+
+### Example of Request Flow animation of a complex server
+
+![Request Flow Animation](assets/request-animation-flow.gif)

fastapi_watchtower-1.0.0/src/fastapi_watchtower.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+src/fastapi_watchtower.egg-info/PKG-INFO
+src/fastapi_watchtower.egg-info/SOURCES.txt
+src/fastapi_watchtower.egg-info/dependency_links.txt
+src/fastapi_watchtower.egg-info/requires.txt
+src/fastapi_watchtower.egg-info/top_level.txt
+src/watchtower/__init__.py
+src/watchtower/api.py
+src/watchtower/artifacts.py
+src/watchtower/expansion.py
+src/watchtower/filtering.py
+src/watchtower/frame_utils.py
+src/watchtower/graph_builder.py
+src/watchtower/indexer.py
+src/watchtower/middleware.py
+src/watchtower/models.py
+src/watchtower/pipeline.py
+src/watchtower/profiler.py
+src/watchtower/serializer.py
+src/watchtower/setup.py
+src/watchtower/trace_parser.py
+src/watchtower/tree_builder.py

fastapi_watchtower-1.0.0/src/fastapi_watchtower.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastapi_watchtower-1.0.0/src/fastapi_watchtower.egg-info/requires.txt

@@ -0,0 +1,5 @@
+fastapi[all]>=0.135.3
+numpy>=2.4.4
+requests>=2.33.1
+twine>=6.2.0
+viztracer>=1.1.1

fastapi_watchtower-1.0.0/src/fastapi_watchtower.egg-info/top_level.txt

@@ -0,0 +1 @@
+watchtower

fastapi_watchtower-1.0.0/src/watchtower/__init__.py

@@ -0,0 +1,4 @@
+from .middleware import WatchTowerMiddleware
+from .setup import setup_watchtower
+
+__all__ = ["WatchTowerMiddleware", "setup_watchtower"]

fastapi_watchtower-1.0.0/src/watchtower/api.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException
+
+
+def create_watchtower_router(output_dir: str = ".watchtower") -> APIRouter:
+    router = APIRouter()
+    watchtower_dir = Path(output_dir)
+
+    @router.get("/requests")
+    async def list_requests():
+        if not watchtower_dir.exists():
+            return {"requests": []}
+
+        results = []
+
+        for request_dir in sorted(
+            [p for p in watchtower_dir.iterdir() if p.is_dir()],
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        ):
+            memory_file = request_dir / "memory.json"
+
+            entry = {
+                "request_id": request_dir.name,
+                "created_at": request_dir.stat().st_mtime,
+                "method": None,
+                "path": None,
+                "duration_ms": None,
+            }
+
+            if memory_file.exists():
+                data = json.loads(memory_file.read_text(encoding="utf-8"))
+                meta = data.get("meta", {})
+                entry["method"] = meta.get("method")
+                entry["path"] = meta.get("path")
+                entry["duration_ms"] = meta.get("duration_ms")
+
+            results.append(entry)
+
+        return {"requests": results}
+
+    @router.get("/requests/latest/graph")
+    async def latest_graph():
+        if not watchtower_dir.exists():
+            raise HTTPException(status_code=404, detail="No WatchTower artifacts found")
+
+        request_dirs = sorted(
+            [p for p in watchtower_dir.iterdir() if p.is_dir()],
+            reverse=True,
+        )
+
+        for request_dir in request_dirs:
+            graph_file = request_dir / "request_graph.json"
+            if graph_file.exists():
+                return json.loads(graph_file.read_text(encoding="utf-8"))
+
+        raise HTTPException(status_code=404, detail="No completed request_graph.json found")
+
+    @router.get("/requests/{request_id}/graph")
+    async def request_graph(request_id: str):
+        graph_file = watchtower_dir / request_id / "request_graph.json"
+
+        if not graph_file.exists():
+            raise HTTPException(status_code=404, detail="request_graph.json not found")
+
+        return json.loads(graph_file.read_text(encoding="utf-8"))
+
+    return router

fastapi_watchtower-1.0.0/src/watchtower/artifacts.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def save_json(data: dict[str, Any], output_file: str) -> None:
+    path = Path(output_file)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")

fastapi_watchtower-1.0.0/src/watchtower/expansion.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def get_child_events_within_range(
+    all_events: list[dict[str, Any]],
+    parent_event: dict[str, Any],
+) -> list[dict[str, Any]]:
+    parent_start = parent_event["ts"]
+    parent_end = parent_event["end_ts"]
+
+    children = []
+    for event in all_events:
+        if event["ts"] < parent_start:
+            continue
+        if (event["ts"] + event["duration_us"]) > parent_end:
+            continue
+        if event["raw_name"] == parent_event.get("raw_name"):
+            continue
+        children.append(event)
+
+    return children

fastapi_watchtower-1.0.0/src/watchtower/filtering.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def _normalize_path(path: str | None) -> str | None:
+    if not path:
+        return None
+    try:
+        return str(Path(path).resolve())
+    except Exception:
+        return str(Path(path))
+
+
+def get_indexed_files(code_index: dict[str, Any]) -> set[str]:
+    files: set[str] = set()
+
+    for module in code_index.get("modules", []):
+        normalized = _normalize_path(module.get("file_path"))
+        if normalized:
+            files.add(normalized)
+
+    return files
+
+
+def filter_user_events(
+    normalized_events: list[dict[str, Any]],
+    indexed_files: set[str],
+) -> list[dict[str, Any]]:
+    filtered: list[dict[str, Any]] = []
+
+    for event in normalized_events:
+        event_file = _normalize_path(event.get("file_path"))
+        if event_file and event_file in indexed_files:
+            filtered.append(
+                {
+                    **event,
+                    "file_path": event_file,
+                }
+            )
+
+    return filtered
+
+
+def _build_module_lookup(code_index: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    lookup: dict[str, dict[str, Any]] = {}
+
+    for module in code_index.get("modules", []):
+        normalized = _normalize_path(module.get("file_path"))
+        if normalized:
+            lookup[normalized] = module
+
+    return lookup
+
+
+def find_matching_function(
+    file_path: str,
+    line_no: int,
+    code_index: dict[str, Any],
+) -> dict[str, Any] | None:
+    normalized_file = _normalize_path(file_path)
+    if not normalized_file:
+        return None
+
+    module_lookup = _build_module_lookup(code_index)
+    module = module_lookup.get(normalized_file)
+    if module is None:
+        return None
+
+    best_match: dict[str, Any] | None = None
+    best_span: int | None = None
+
+    for fn in module.get("functions", []):
+        start = fn["lineno"]
+        end = fn.get("end_lineno") or start
+        if start <= line_no <= end:
+            span = end - start
+            if best_span is None or span < best_span:
+                best_match = fn
+                best_span = span
+
+    for cls in module.get("classes", []):
+        for method in cls.get("methods", []):
+            start = method["lineno"]
+            end = method.get("end_lineno") or start
+            if start <= line_no <= end:
+                span = end - start
+                if best_span is None or span < best_span:
+                    best_match = method
+                    best_span = span
+
+    return best_match
+
+
+def attach_index_metadata(
+    events: list[dict[str, Any]],
+    code_index: dict[str, Any],
+) -> list[dict[str, Any]]:
+    enriched: list[dict[str, Any]] = []
+
+    sorted_events = sorted(events, key=lambda e: (e["ts"], e.get("duration_us", 0)))
+
+    for idx, event in enumerate(sorted_events, start=1):
+        match = find_matching_function(
+            file_path=event["file_path"],
+            line_no=event["line_no"],
+            code_index=code_index,
+        )
+        if match is None:
+            continue
+
+        enriched.append(
+            {
+                **event,
+                "file_path": _normalize_path(event["file_path"]),
+                "qualified_name": match["qualified_name"],
+                "route_path": match.get("route_path"),
+                "route_methods": match.get("route_methods", []),
+                "parent_class": match.get("parent_class"),
+                "call_index": idx,
+            }
+        )
+
+    return enriched

fastapi_watchtower-1.0.0/src/watchtower/frame_utils.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import inspect
+
+from .serializer import safe_serialize
+
+DEFAULT_SKIPPED_ARG_NAMES = {"request", "response", "app", "db"}
+
+
+def extract_inputs_from_frame(
+    frame,
+    *,
+    include_self: bool = False,
+    max_depth: int = 2,
+    max_string_length: int = 200,
+    max_collection_items: int = 10,
+) -> dict:
+    arg_info = inspect.getargvalues(frame)
+
+    args_out = []
+    kwargs_out = {}
+
+    skipped = set(DEFAULT_SKIPPED_ARG_NAMES)
+    if not include_self:
+        skipped.update({"self", "cls"})
+
+    for name in arg_info.args:
+        if name in skipped:
+            continue
+
+        value = arg_info.locals.get(name)
+        args_out.append(
+            {
+                "name": name,
+                "value": safe_serialize(
+                    value,
+                    max_depth=max_depth,
+                    max_string_length=max_string_length,
+                    max_collection_items=max_collection_items,
+                ),
+            }
+        )
+
+    if arg_info.varargs:
+        varargs_value = arg_info.locals.get(arg_info.varargs, ())
+        args_out.append(
+            {
+                "name": f"*{arg_info.varargs}",
+                "value": safe_serialize(
+                    varargs_value,
+                    max_depth=max_depth,
+                    max_string_length=max_string_length,
+                    max_collection_items=max_collection_items,
+                ),
+            }
+        )
+
+    if arg_info.keywords:
+        kw_value = arg_info.locals.get(arg_info.keywords, {})
+        if isinstance(kw_value, dict):
+            kwargs_out = {
+                str(k): safe_serialize(
+                    v,
+                    max_depth=max_depth,
+                    max_string_length=max_string_length,
+                    max_collection_items=max_collection_items,
+                )
+                for k, v in kw_value.items()
+            }
+        else:
+            kwargs_out = {
+                f"**{arg_info.keywords}": safe_serialize(
+                    kw_value,
+                    max_depth=max_depth,
+                    max_string_length=max_string_length,
+                    max_collection_items=max_collection_items,
+                )
+            }
+
+    class_name = None
+    if "self" in frame.f_locals:
+        class_name = type(frame.f_locals["self"]).__name__
+    elif "cls" in frame.f_locals and hasattr(frame.f_locals["cls"], "__name__"):
+        class_name = frame.f_locals["cls"].__name__
+
+    return {
+        "class_name": class_name,
+        "inputs": {
+            "args": args_out,
+            "kwargs": kwargs_out,
+        },
+    }

fastapi_watchtower-1.0.0/src/watchtower/graph_builder.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _short_label(name: str) -> str:
+    if "." in name:
+        return name.split(".")[-1]
+    return name
+
+
+def tree_to_graph(tree: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
+    nodes: list[dict[str, Any]] = []
+    edges: list[dict[str, Any]] = []
+
+    def visit(node: dict[str, Any], parent_id: str | None = None, depth: int = 0) -> None:
+        node_id = node["id"]
+        node_type = "request" if depth == 0 else "function"
+
+        nodes.append(
+            {
+                "id": node_id,
+                "label": _short_label(node["name"]),
+                "full_name": node["name"],
+                "type": node_type,
+                "duration": node.get("dur", node.get("duration_ms")),
+                "file_path": node.get("file_path"),
+                "line_no": node.get("line_no"),
+                "route_path": node.get("route_path"),
+                "route_methods": node.get("route_methods", []),
+                "parent_class": node.get("parent_class"),
+                "call_index": node.get("call_index"),
+                "inputs": node.get("inputs"),
+                "raw_args": node.get("raw_args"),
+                "request_id": node.get("request_id"),
+                "created_at": node.get("created_at"),
+                "expandable": len(node.get("children", [])) > 0,
+            }
+        )
+
+        if parent_id is not None:
+            edges.append(
+                {
+                    "id": f"{parent_id}->{node_id}",
+                    "source": parent_id,
+                    "target": node_id,
+                }
+            )
+
+        for child in node.get("children", []):
+            visit(child, node_id, depth + 1)
+
+    visit(tree)
+    return {"nodes": nodes, "edges": edges}