tracelink 0.5.0__tar.gz

tracelink-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 秦权 (Qin Quan)
+
+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.

tracelink-0.5.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: tracelink
+Version: 0.5.0
+Summary: Full-stack cross-end debug tracer — NDJSON + readable, scope-filtered, AI-friendly
+Author-email: qinquan-ai <qin16778@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/qinquan-ai/Trace_Link
+Project-URL: Documentation, https://github.com/qinquan-ai/Trace_Link#readme
+Project-URL: Issues, https://github.com/qinquan-ai/Trace_Link/issues
+Project-URL: Changelog, https://github.com/qinquan-ai/Trace_Link/blob/main/CHANGELOG.md
+Keywords: tracing,debug,logging,ndjson,skill,ai-agent,scope,fastapi,starlette
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.7; extra == "dev"
+Dynamic: license-file
+
+# tracelink
+
+Full-stack cross-end debug tracer — NDJSON + readable, scope-filtered, AI-friendly.
+
+## Install
+
+```bash
+pip install tracelink
+```
+
+With FastAPI/Starlette support:
+
+```bash
+pip install tracelink[fastapi]
+```
+
+## Quick Start
+
+```python
+from tracelink import debug_tracer
+
+debug_tracer.start_scope('delete-work')
+debug_tracer.entry('router.py:delete', 'user clicked delete', {'user_id': 123}, scope='delete-work')
+debug_tracer.end_scope('delete-work')
+```
+
+## Send to the TraceLink board (0.5.0)
+
+The Python sender has HTTP parity with the Node sender: point it at the same
+standalone receiver + dashboard (started from the JS package via
+`npx @qin16778/tracelink board`, default port `5174`) and Python and Node traces
+land on one board, correlated by `traceId`.
+
+```python
+from tracelink import debug_tracer
+
+# non-blocking, fail-safe HTTP sink -> the board
+debug_tracer.configure(http_endpoint="http://127.0.0.1:5174/__debug_log")
+```
+
+First-run checklist (or you'll see nothing on the board):
+
+- **Start the board first.** The receiver lives in the JS package; run
+  `npx @qin16778/tracelink board` before your Python process emits.
+- **Enable tracing.** It's on when a dev/debug env is set; otherwise force it
+  with `TRACELINK_ENABLED=1` or `debug_tracer.set_enabled(True)`.
+- **Flush short scripts.** Delivery is fire-and-forget on a daemon thread; for a
+  short-lived script call `sink.flush()` before exit (the sink returned by
+  `configure()`), so the last events land.
+
+## AI-agent spans (0.5.0)
+
+```python
+from tracelink import debug_tracer
+
+async def body():
+    debug_tracer.blocked('agent.py:sub', 'write outside sandbox denied',
+                         reason='permission denied', data={'path': '/etc/passwd'})
+
+await debug_tracer.span('X-AGENT', 'agent.py:run', 'agent.run', body, scope='agent-run-py')
+```
+
+Spans auto-nest via `contextvars` (correct across `await`); the close event
+carries real `durationMs` + `async`, and `blocked` / `intent` set `outcome`. See
+the cross-language flagship demo:
+[`examples/ai-agent`](https://github.com/qinquan-ai/Trace_Link/tree/main/examples/ai-agent).
+
+## Features
+
+- **AI-agent native**: `debug_tracer.span()` with auto `traceId`/`parentSpanId` nesting (`contextvars`), `durationMs`, `async`, and `outcome` (`call` / `blocked` / `intent`).
+- **Severity levels**: `level` (`debug` / `info` / `warn` / `error`) for board filtering + coloring.
+- **Scope-filtered**: group related log entries by scope name
+- **AI-friendly NDJSON**: each entry is one JSON line, easy for AI agents to parse
+- **Zero dependencies**: core uses only Python stdlib
+- **FastAPI/Starlette middleware**: plug-and-play HTTP middleware
+- **Shared board**: POST to the JS receiver so Python + Node traces render on one dashboard
+
+## CLI
+
+```bash
+tracelink --port 8080
+```
+
+## Links
+
+- [Homepage](https://github.com/qinquan-ai/Trace_Link)
+- [Documentation](https://github.com/qinquan-ai/Trace_Link#readme)
+- [Issues](https://github.com/qinquan-ai/Trace_Link/issues)

tracelink-0.5.0/README.md

@@ -0,0 +1,88 @@
+# tracelink
+
+Full-stack cross-end debug tracer — NDJSON + readable, scope-filtered, AI-friendly.
+
+## Install
+
+```bash
+pip install tracelink
+```
+
+With FastAPI/Starlette support:
+
+```bash
+pip install tracelink[fastapi]
+```
+
+## Quick Start
+
+```python
+from tracelink import debug_tracer
+
+debug_tracer.start_scope('delete-work')
+debug_tracer.entry('router.py:delete', 'user clicked delete', {'user_id': 123}, scope='delete-work')
+debug_tracer.end_scope('delete-work')
+```
+
+## Send to the TraceLink board (0.5.0)
+
+The Python sender has HTTP parity with the Node sender: point it at the same
+standalone receiver + dashboard (started from the JS package via
+`npx @qin16778/tracelink board`, default port `5174`) and Python and Node traces
+land on one board, correlated by `traceId`.
+
+```python
+from tracelink import debug_tracer
+
+# non-blocking, fail-safe HTTP sink -> the board
+debug_tracer.configure(http_endpoint="http://127.0.0.1:5174/__debug_log")
+```
+
+First-run checklist (or you'll see nothing on the board):
+
+- **Start the board first.** The receiver lives in the JS package; run
+  `npx @qin16778/tracelink board` before your Python process emits.
+- **Enable tracing.** It's on when a dev/debug env is set; otherwise force it
+  with `TRACELINK_ENABLED=1` or `debug_tracer.set_enabled(True)`.
+- **Flush short scripts.** Delivery is fire-and-forget on a daemon thread; for a
+  short-lived script call `sink.flush()` before exit (the sink returned by
+  `configure()`), so the last events land.
+
+## AI-agent spans (0.5.0)
+
+```python
+from tracelink import debug_tracer
+
+async def body():
+    debug_tracer.blocked('agent.py:sub', 'write outside sandbox denied',
+                         reason='permission denied', data={'path': '/etc/passwd'})
+
+await debug_tracer.span('X-AGENT', 'agent.py:run', 'agent.run', body, scope='agent-run-py')
+```
+
+Spans auto-nest via `contextvars` (correct across `await`); the close event
+carries real `durationMs` + `async`, and `blocked` / `intent` set `outcome`. See
+the cross-language flagship demo:
+[`examples/ai-agent`](https://github.com/qinquan-ai/Trace_Link/tree/main/examples/ai-agent).
+
+## Features
+
+- **AI-agent native**: `debug_tracer.span()` with auto `traceId`/`parentSpanId` nesting (`contextvars`), `durationMs`, `async`, and `outcome` (`call` / `blocked` / `intent`).
+- **Severity levels**: `level` (`debug` / `info` / `warn` / `error`) for board filtering + coloring.
+- **Scope-filtered**: group related log entries by scope name
+- **AI-friendly NDJSON**: each entry is one JSON line, easy for AI agents to parse
+- **Zero dependencies**: core uses only Python stdlib
+- **FastAPI/Starlette middleware**: plug-and-play HTTP middleware
+- **Shared board**: POST to the JS receiver so Python + Node traces render on one dashboard
+
+## CLI
+
+```bash
+tracelink --port 8080
+```
+
+## Links
+
+- [Homepage](https://github.com/qinquan-ai/Trace_Link)
+- [Documentation](https://github.com/qinquan-ai/Trace_Link#readme)
+- [Issues](https://github.com/qinquan-ai/Trace_Link/issues)

tracelink-0.5.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tracelink"
+version = "0.5.0"
+description = "Full-stack cross-end debug tracer — NDJSON + readable, scope-filtered, AI-friendly"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [
+    { name = "qinquan-ai", email = "qin16778@gmail.com" },
+]
+keywords = ["tracing", "debug", "logging", "ndjson", "skill", "ai-agent", "scope", "fastapi", "starlette"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Logging",
+]
+dependencies = [
+    # Intentionally empty — tracelink core uses only stdlib.
+    # FastAPI/Starlette are peer deps so users can choose their version.
+]
+
+[project.optional-dependencies]
+fastapi = ["starlette>=0.27"]
+dev = [
+    "pytest>=7.4",
+    "pytest-asyncio>=0.21",
+    "ruff>=0.1.0",
+    "mypy>=1.7",
+]
+
+[project.scripts]
+tracelink = "tracelink.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/qinquan-ai/Trace_Link"
+Documentation = "https://github.com/qinquan-ai/Trace_Link#readme"
+Issues = "https://github.com/qinquan-ai/Trace_Link/issues"
+Changelog = "https://github.com/qinquan-ai/Trace_Link/blob/main/CHANGELOG.md"
+
+[tool.setuptools]
+package-dir = { "" = "." }
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tracelink*"]
+exclude = ["tests*", "examples*"]
+
+[tool.setuptools.package-data]
+tracelink = ["py.typed"]
+"tracelink.dashboard" = ["static/*"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "ASYNC"]
+ignore = ["E501"]  # line-length handled by formatter
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

tracelink-0.5.0/setup.cfg

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

tracelink-0.5.0/tests/test_sinks.py

@@ -0,0 +1,211 @@
+"""Sink fan-out + HTTP sink tests (0.5.0).
+
+Covers the parity work with the JS tracer:
+  - `add_sink` fan-out (every built log reaches every registered sink),
+    unsubscribe, and fail-safe isolation (a raising sink never breaks tracing);
+  - the `HttpSink` transport: POSTs each `TraceLog` as JSON to `/__debug_log`
+    with `x-trace-id` / `x-debug-scopes` headers, carrying the 0.5.0 fields
+    (`level` / `outcome` / `durationMs` / `async` / `data.reason`).
+"""
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from tracelink.sinks.http import HttpSink
+
+
+@pytest.fixture
+def isolated_tracer(tmp_path, monkeypatch):
+    """Redirect log paths to a temp dir and reset the live singleton state,
+    including the new sink registry / HTTP-sink slot."""
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("TRACELINK_DIR", str(tmp_path))
+    monkeypatch.setenv("TRACELINK_ENABLED", "true")
+    import tracelink.tracer as tracer_mod
+
+    inst = tracer_mod.debug_tracer
+    inst._enabled = True
+    inst._enabled_scopes = {"*"}
+    inst._logs = []
+    inst._active_traces = {}
+    inst._trace_id = None
+    inst._span_counter = 0
+    inst._sinks = []
+    inst._http_sink = None
+    yield inst
+    # Teardown — drop any HTTP sink thread and custom sinks.
+    if inst._http_sink is not None and hasattr(inst._http_sink, "close"):
+        inst._http_sink.close(timeout=1.0)
+    inst._http_sink = None
+    inst._sinks = []
+    inst._logs = []
+    inst._active_traces = {}
+    inst._enabled_scopes = {"*"}
+
+
+# ---------------------------------------------------------------------------
+# add_sink fan-out
+# ---------------------------------------------------------------------------
+
+
+def test_add_sink_receives_built_log(isolated_tracer):
+    received = []
+    isolated_tracer.add_sink(received.append)
+
+    isolated_tracer.entry("router.py:x", "hi", {"a": 1}, level="info", scope="s")
+
+    assert len(received) == 1
+    log = received[0]
+    assert log["layer"] == "BE-ENTRY"
+    assert log["msg"] == "hi"
+    assert log["level"] == "info"
+    assert log["data"]["a"] == 1
+    # Same dict that hit the memory buffer (built once, fanned out).
+    assert isolated_tracer.get_logs()[-1] is log
+
+
+def test_add_sink_unsubscribe_stops_delivery(isolated_tracer):
+    received = []
+    off = isolated_tracer.add_sink(received.append)
+
+    isolated_tracer.entry("x", "one", scope="s")
+    off()
+    isolated_tracer.entry("x", "two", scope="s")
+
+    assert [log["msg"] for log in received] == ["one"]
+
+
+def test_sink_raising_does_not_break_tracing(isolated_tracer):
+    calls = {"good": 0}
+
+    def boom(_log):
+        raise RuntimeError("sink blew up")
+
+    def good(_log):
+        calls["good"] += 1
+
+    isolated_tracer.add_sink(boom)
+    isolated_tracer.add_sink(good)
+
+    # Must not raise into user code, and the healthy sink still runs.
+    isolated_tracer.entry("x", "resilient", scope="s")
+
+    assert calls["good"] == 1
+    assert isolated_tracer.get_logs()[-1]["msg"] == "resilient"
+
+
+def test_fan_out_covers_http_slot_and_custom_sinks(isolated_tracer):
+    http_seen = []
+    custom_seen = []
+    isolated_tracer.configure(http_sink=http_seen.append)
+    isolated_tracer.add_sink(custom_seen.append)
+
+    isolated_tracer.entry("x", "both", scope="s")
+
+    assert len(http_seen) == 1
+    assert len(custom_seen) == 1
+    assert http_seen[0]["msg"] == "both"
+
+
+# ---------------------------------------------------------------------------
+# HttpSink transport
+# ---------------------------------------------------------------------------
+
+
+class _CaptureHandler(BaseHTTPRequestHandler):
+    received = []  # class-level; reset per server in the fixture
+
+    def do_POST(self):  # noqa: N802 - http.server naming
+        length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(length).decode("utf-8")
+        type(self).received.append(
+            {
+                "path": self.path,
+                "headers": {k.lower(): v for k, v in self.headers.items()},
+                "body": body,
+            }
+        )
+        self.send_response(204)
+        self.end_headers()
+
+    def log_message(self, *_args):  # silence the default stderr spam
+        pass
+
+
+@pytest.fixture
+def capture_server():
+    _CaptureHandler.received = []
+    server = HTTPServer(("127.0.0.1", 0), _CaptureHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    host, port = server.server_address
+    yield f"http://{host}:{port}/__debug_log", _CaptureHandler.received
+    server.shutdown()
+    server.server_close()
+    thread.join(timeout=2)
+
+
+def test_http_sink_posts_all_050_fields(isolated_tracer, capture_server):
+    endpoint, received = capture_server
+
+    sink = isolated_tracer.configure(http_endpoint=endpoint)
+
+    # A blocked outcome (outcome + level=warn + data.reason).
+    isolated_tracer.blocked(
+        "routes/work:delete", "DELETE rejected",
+        reason="insufficient permission", data={"workId": "w_1"}, scope="s",
+    )
+    # An error-level normal log (level variety).
+    isolated_tracer.entry("router.py:boom", "non-fatal", level="error", scope="s")
+    # A span → open + close; close carries durationMs + async.
+    isolated_tracer.span("BE-ENTRY", "router.py:h", "handle", lambda: None, scope="s")
+
+    # Wait for the background daemon thread to drain.
+    assert sink.flush(timeout=3) is True
+
+    # 1 blocked + 1 entry + 2 span events (open, close) = 4 POSTs.
+    assert len(received) == 4
+
+    for req in received:
+        assert req["path"] == "/__debug_log"
+        assert req["headers"]["content-type"] == "application/json"
+        assert "x-trace-id" in req["headers"]
+        assert json.loads(req["headers"]["x-debug-scopes"]) == ["*"]
+
+    bodies = [json.loads(r["body"]) for r in received]
+    by_msg = {b["msg"]: b for b in bodies}
+
+    blocked_log = by_msg["DELETE rejected"]
+    assert blocked_log["outcome"] == "blocked"
+    assert blocked_log["level"] == "warn"
+    assert blocked_log["data"]["reason"] == "insufficient permission"
+
+    assert by_msg["non-fatal"]["level"] == "error"
+
+    # The span-close body carries durationMs + async (reserved key serialized).
+    close_logs = [b for b in bodies if "durationMs" in b]
+    assert len(close_logs) == 1
+    assert isinstance(close_logs[0]["durationMs"], int)
+    assert close_logs[0]["async"] is False
+
+
+def test_http_sink_send_is_failsafe_when_receiver_down(isolated_tracer):
+    # Point at a closed port; send() must not block or raise, tracing continues.
+    sink = HttpSink(endpoint="http://127.0.0.1:59999/__debug_log", timeout_ms=200)
+    isolated_tracer.add_sink(sink)
+
+    isolated_tracer.entry("x", "no receiver", scope="s")  # must not raise
+    sink.flush(timeout=1)  # background delivery fails silently
+
+    assert isolated_tracer.get_logs()[-1]["msg"] == "no receiver"
+    sink.close(timeout=1)
+
+
+def test_http_sink_disabled_is_noop(isolated_tracer):
+    sink = HttpSink(endpoint="http://127.0.0.1:59999/__debug_log", disabled=True)
+    # No worker thread should be spawned while disabled.
+    sink.send({"traceId": "t", "msg": "x"})
+    assert sink._worker is None