traceact 0.6.2__tar.gz → 0.8.0__tar.gz

{traceact-0.6.2/traceact.egg-info → traceact-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.6.2
+Version: 0.8.0
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -55,6 +55,7 @@ pip install traceact
 from traceact import traced_action, configure, TraceConfig, JsonlSink
 
 configure(
+    project="my-app",
     config=TraceConfig(sink_mode="blocking"),
     sinks=[JsonlSink("data/traces.jsonl")],
 )

{traceact-0.6.2 → traceact-0.8.0}/README.md

@@ -20,6 +20,7 @@ pip install traceact
 from traceact import traced_action, configure, TraceConfig, JsonlSink
 
 configure(
+    project="my-app",
     config=TraceConfig(sink_mode="blocking"),
     sinks=[JsonlSink("data/traces.jsonl")],
 )

{traceact-0.6.2 → traceact-0.8.0}/USAGE.md

@@ -94,6 +94,7 @@ Call `configure()` once at application startup before any traces run.
 from traceact import configure, TraceConfig, TraceBudget, JsonlSink, ConsoleSink
 
 configure(
+    project="my-app",           # stamps every trace; viewer uses this as the source name
     config=TraceConfig(
         enabled=True,
         sink_mode="blocking",   # "blocking" | "buffered" | "disabled"
@@ -119,6 +120,8 @@ configure(
 
 All fields are optional. Omitted fields use package defaults. `configure()` can be called multiple times; later calls replace earlier ones.
 
+**`project`** is the recommended way to name your traces. It is stamped onto every trace produced by this process and used by the viewer to label the source. Traces written without a `project` emit a `UserWarning` at runtime. A per-trace `project=` argument on `@traced_action` or `ActionTrace.start()` overrides the package-level value for that trace only.
+
 **Sink modes:**
 - `"blocking"` — write immediately when a trace finishes. Best for development.
 - `"buffered"` — hold traces in memory, flush on exit or on explicit `flush_buffer()`. Best for production.
@@ -1447,9 +1450,32 @@ launch_or_connect(
     port=8765,        # port to try if starting a new viewer
     open_browser=False,
     timeout=3.0,      # seconds to wait for a freshly started server to be ready
-) -> str              # returns the viewer URL, e.g. "http://127.0.0.1:8765/"
+    name=None,        # label for this source in the picker; derived from the path if unset
+) -> str              # returns the viewer URL, e.g. "http://127.0.0.1:8765/?source=agora"
 ```
 
+### How sources are named
+
+The viewer labels each source in its picker. Left to itself it derives the name from the path, skipping components that describe storage rather than a project (`traces`, `data`, `logs`, `output`, `var`, `tmp`, and similar):
+
+| Path | Name |
+|---|---|
+| `~/Dev/agora/data/traces/traces.jsonl` | `agora` |
+| `~/Dev/casewright/logs/traces.jsonl` | `casewright` |
+| `~/Dev/agora/agora_traces.jsonl` | `agora_traces` |
+| `~/Dev/agora/data/traces/worker.jsonl` | `worker` |
+| `~/Dev/agora/data/traces/traces.1234.jsonl` | `agora` |
+
+A filename that already identifies the project is used as-is, so an app that writes `agora_traces.jsonl` keeps that name. Only a generic filename falls through to the directory walk. Per-process shards and rotated segments reduce to the same project name, so they don't fill the picker with near-identical entries.
+
+Pass `name` when the app knows its own identity and shouldn't depend on where its files sit:
+
+```python
+launch_or_connect(source="data/traces/traces.jsonl", name="agora")
+```
+
+Sources are deduplicated by resolved path, so calling `launch_or_connect()` on every run reuses the existing entry rather than adding `agora-2`, `agora-3`, … Two different paths that derive the same name still get a numeric suffix to stay distinguishable.
+
 ### Frontend button
 
 The button should be a `<button>` (not an `<a href>`), so you can disable it and show a loading state while the backend starts the viewer:

{traceact-0.6.2 → traceact-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "traceact"
-version = "0.6.2"
+version = "0.8.0"
 description = "X-ray vision for your code. Lightweight action-level tracing for Python."
 readme = "README.md"
 requires-python = ">=3.9"

traceact-0.8.0/tests/test_project_name.py

@@ -0,0 +1,153 @@
+# tests/test_project_name.py
+#
+# Tests for configure(project=...), project cascading to traces, and the
+# warning emitted when a root trace is written without a project name.
+
+import warnings
+
+import pytest
+
+import traceact
+from traceact import ActionTrace, configure, reset_config
+from traceact.config import get_package_project
+from traceact.trace import _create_trace
+
+
+# ---------------------------------------------------------------------------
+# configure(project=...) — package-level state
+# ---------------------------------------------------------------------------
+
+class TestConfigureProject:
+    def test_project_stored_in_package_state(self):
+        configure(project="agora")
+        assert get_package_project() == "agora"
+
+    def test_reset_clears_project(self):
+        configure(project="agora")
+        reset_config()
+        assert get_package_project() is None
+
+    def test_configure_without_project_does_not_clear_existing(self):
+        configure(project="agora")
+        configure()  # no project arg
+        assert get_package_project() == "agora"
+
+    def test_configure_project_can_be_updated(self):
+        configure(project="alpha")
+        configure(project="beta")
+        assert get_package_project() == "beta"
+
+
+# ---------------------------------------------------------------------------
+# Project cascading — package → trace
+# ---------------------------------------------------------------------------
+
+class TestProjectCascade:
+    def test_package_project_stamped_onto_trace(self, tmp_path):
+        configure(project="agora")
+        with ActionTrace.start(action="test.run") as trace:
+            pass
+        assert trace.project == "agora"
+
+    def test_per_trace_project_overrides_package(self, tmp_path):
+        configure(project="agora")
+        with ActionTrace.start(action="test.run", project="override") as trace:
+            pass
+        assert trace.project == "override"
+
+    def test_child_inherits_package_project(self):
+        configure(project="agora")
+        with ActionTrace.start(action="parent") as parent:
+            with ActionTrace.start(action="child") as child:
+                pass
+        assert child.project == "agora"
+
+    def test_child_inherits_parent_project_when_package_unset(self):
+        with ActionTrace.start(action="parent", project="manual") as parent:
+            with ActionTrace.start(action="child") as child:
+                pass
+        assert child.project == "manual"
+
+    def test_package_project_wins_over_parent_project(self):
+        # Package is the top of the cascade — it overrides even an explicit
+        # parent project so that configure(project=...) is a single source of
+        # truth for the whole app.
+        configure(project="package-level")
+        with ActionTrace.start(action="parent", project="parent-level") as parent:
+            with ActionTrace.start(action="child") as child:
+                pass
+        assert child.project == "package-level"
+
+    def test_no_project_anywhere_leaves_none(self):
+        with ActionTrace.start(action="test.run") as trace:
+            pass
+        assert trace.project is None
+
+    def test_project_appears_in_serialised_record(self, tmp_path):
+        import json
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(
+            project="agora",
+            config=traceact.TraceConfig(sink_mode="blocking"),
+            sinks=[traceact.JsonlSink(str(f))],
+        )
+        with ActionTrace.start(action="test.run"):
+            pass
+        records = [json.loads(l) for l in f.read_text().splitlines() if l.strip()]
+        assert records[-1]["project"] == "agora"
+
+
+# ---------------------------------------------------------------------------
+# Warning on unnamed root traces
+# ---------------------------------------------------------------------------
+
+class TestUnnamedTraceWarning:
+    def test_warns_when_no_project_set(self, tmp_path):
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="test.run"):
+                pass
+        msgs = [str(w.message) for w in caught if issubclass(w.category, UserWarning)]
+        assert any("project" in m for m in msgs)
+
+    def test_no_warning_when_project_set_via_configure(self, tmp_path):
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(project="agora", sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="test.run"):
+                pass
+        msgs = [str(w.message) for w in caught if issubclass(w.category, UserWarning)]
+        assert not any("project" in m for m in msgs)
+
+    def test_no_warning_when_project_set_per_trace(self, tmp_path):
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="test.run", project="agora"):
+                pass
+        msgs = [str(w.message) for w in caught if issubclass(w.category, UserWarning)]
+        assert not any("project" in m for m in msgs)
+
+    def test_child_trace_does_not_warn(self, tmp_path):
+        # Only root traces warn — spamming for every child would be noise.
+        import traceact
+        f = tmp_path / "traces.jsonl"
+        traceact.configure(sinks=[traceact.JsonlSink(str(f))])
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            with ActionTrace.start(action="parent"):
+                with ActionTrace.start(action="child"):
+                    pass
+        project_warnings = [
+            w for w in caught
+            if issubclass(w.category, UserWarning) and "project" in str(w.message)
+        ]
+        # At most one warning (the root), never two.
+        assert len(project_warnings) <= 1

{traceact-0.6.2 → traceact-0.8.0}/tests/test_viewer_instance.py

@@ -12,7 +12,72 @@ import unittest.mock as mock
 
 import pytest
 
-from traceact.viewer.server import ViewerState
+from traceact.viewer.server import ViewerState, _derive_name
+
+
+# ---------------------------------------------------------------------------
+# Source naming
+# ---------------------------------------------------------------------------
+#
+# Nearly every app writes to some variant of <project>/data/traces/traces.jsonl,
+# so a name taken from the filename alone reads "traces" for every project on
+# the machine. These assert the name identifies the project instead.
+
+class TestDeriveName:
+    def test_skips_generic_dirs_to_project_name(self):
+        assert _derive_name("/Users/mo/Dev/agora/data/traces/traces.jsonl") == "agora"
+
+    def test_skips_logs_dir(self):
+        assert _derive_name("/Users/mo/Dev/casewright/logs/traces.jsonl") == "casewright"
+
+    def test_two_projects_get_different_names(self):
+        # The whole point: same filename, same layout, different projects.
+        a = _derive_name("/Users/mo/Dev/agora/data/traces/traces.jsonl")
+        b = _derive_name("/Users/mo/Dev/casewright/data/traces/traces.jsonl")
+        assert a != b
+
+    def test_specific_filename_is_honoured(self):
+        # An app that already names its file per project keeps that name —
+        # the directory walk is only a fallback for generic filenames.
+        assert _derive_name("/Users/mo/Dev/agora/agora_traces.jsonl") == "agora_traces"
+
+    def test_non_generic_filename_wins_over_dir(self):
+        assert _derive_name("/Users/mo/Dev/agora/data/traces/worker.jsonl") == "worker"
+
+    def test_hidden_project_dir_loses_leading_dot(self):
+        assert _derive_name("/Users/mo/.tree/traces/traces.jsonl") == "tree"
+
+    def test_pid_shard_derives_project_not_shard(self):
+        # All shards of one project must derive the same name, or a sharded
+        # app fills the picker with near-identical entries.
+        a = _derive_name("/Users/mo/Dev/agora/data/traces/traces.1234.jsonl")
+        b = _derive_name("/Users/mo/Dev/agora/data/traces/traces.5678.jsonl")
+        assert a == b == "agora"
+
+    def test_rotated_segment_derives_project(self):
+        path = "/Users/mo/Dev/agora/data/traces/traces.20260726T120000000000Z.jsonl"
+        assert _derive_name(path) == "agora"
+
+    def test_folder_source_skips_generic_components(self):
+        assert _derive_name("/Users/mo/Dev/agora/data/traces") == "agora"
+
+    def test_all_generic_falls_back(self):
+        assert _derive_name("/data/traces/traces.jsonl") == "source"
+
+    def test_generic_matching_is_case_insensitive(self):
+        assert _derive_name("/Users/mo/Dev/agora/Data/Traces/Traces.jsonl") == "agora"
+
+    def test_traceact_state_dir_is_generic(self):
+        assert _derive_name("/Users/mo/.traceact/imports/dropped.jsonl") == "dropped"
+
+    def test_bare_filename_does_not_crash(self):
+        assert _derive_name("traces.jsonl") == "source"
+
+    def test_explicit_name_overrides_derivation(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        assert state.add_source(str(f), name="agora") == "agora"
 
 
 # ---------------------------------------------------------------------------
@@ -32,12 +97,15 @@ class TestAddSourceDedupe:
     def test_repeated_adds_do_not_accumulate(self, tmp_path):
         # The reported symptom: an app calling launch_or_connect() on every
         # run produced traces-2, traces-3, traces-4 ... for one unchanging file.
+        # Asserts the dedupe property, not the derived name — the name comes
+        # from the tmp directory here and is covered by TestDeriveName.
         f = tmp_path / "traces.jsonl"
         f.write_text("")
         state = ViewerState()
         for _ in range(5):
             state.add_source(str(f))
-        assert list(state.sources) == ["traces"]
+        assert len(state.sources) == 1
+        assert not any(n.endswith("-2") for n in state.sources)
 
     def test_relative_and_absolute_path_dedupe(self, tmp_path, monkeypatch):
         f = tmp_path / "traces.jsonl"
@@ -129,6 +197,58 @@ class TestLaunchOrConnectSourcePin:
             url = instance.launch_or_connect()
         assert url == "http://127.0.0.1:8765/"
 
+    def test_explicit_name_forwarded_to_add_source(self):
+        from traceact.viewer import instance
+
+        with mock.patch.object(
+            instance, "find_running",
+            return_value={"host": "127.0.0.1", "port": 8765},
+        ), mock.patch.object(
+            instance, "add_source_to",
+            return_value={"name": "agora", "path": "/x/traces.jsonl"},
+        ) as add:
+            url = instance.launch_or_connect(source="/x/traces.jsonl", name="agora")
+        assert add.call_args.kwargs["name"] == "agora"
+        assert url == "http://127.0.0.1:8765/?source=agora"
+
+    def test_add_source_to_omits_name_when_not_given(self):
+        # The payload must not carry name=None; the server treats a missing
+        # name as "derive one" and an explicit null would be a different case.
+        from traceact.viewer import instance
+
+        captured = {}
+
+        class FakeResp:
+            def __enter__(self): return self
+            def __exit__(self, *a): return False
+            def read(self): return b'{"name":"x","path":"/x"}'
+
+        def fake_urlopen(req, timeout=None):
+            captured["body"] = json.loads(req.data.decode())
+            return FakeResp()
+
+        with mock.patch("urllib.request.urlopen", side_effect=fake_urlopen):
+            instance.add_source_to("127.0.0.1", 8765, "/x/traces.jsonl")
+        assert captured["body"] == {"path": "/x/traces.jsonl"}
+
+    def test_add_source_to_includes_name_when_given(self):
+        from traceact.viewer import instance
+
+        captured = {}
+
+        class FakeResp:
+            def __enter__(self): return self
+            def __exit__(self, *a): return False
+            def read(self): return b'{"name":"agora","path":"/x"}'
+
+        def fake_urlopen(req, timeout=None):
+            captured["body"] = json.loads(req.data.decode())
+            return FakeResp()
+
+        with mock.patch("urllib.request.urlopen", side_effect=fake_urlopen):
+            instance.add_source_to("127.0.0.1", 8765, "/x/traces.jsonl", name="agora")
+        assert captured["body"]["name"] == "agora"
+
     def test_failed_add_falls_back_to_bare_url(self):
         # add_source_to returns None when the running viewer can't be reached;
         # a URL pinning a source that was never registered would be worse than
@@ -255,3 +375,87 @@ class TestPrivateInstanceStateGating:
         rc, _, clear_state = self._run_view(["view", "--no-browser"], monkeypatch)
         assert rc == 0
         assert clear_state.called
+
+
+# ---------------------------------------------------------------------------
+# Project-field-based source naming
+# ---------------------------------------------------------------------------
+#
+# When a source contains trace records with a non-null project field, the
+# viewer uses that value as the source name rather than deriving it from the
+# file path. This keeps the name stable even if the file is moved, and works
+# identically for JSONL, SQLite, and future HTTP sources.
+
+import json as _json  # already imported above, but named alias avoids shadowing
+
+
+class TestProjectFieldNaming:
+    def _write_traces(self, path, records):
+        with open(path, "w", encoding="utf-8") as fh:
+            for r in records:
+                fh.write(_json.dumps(r) + "\n")
+
+    def test_project_field_used_as_source_name(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": "agora", "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert name == "agora"
+
+    def test_project_name_marked_as_named(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": "agora", "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert state.source_named[name] is True
+
+    def test_path_derived_name_marked_as_unnamed(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert state.source_named[name] is False
+
+    def test_empty_source_falls_back_to_path(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        f.write_text("")
+        # Empty file has no project — must not crash and must produce a name.
+        state = ViewerState()
+        name = state.add_source(str(f))
+        assert name  # non-empty
+
+    def test_null_project_falls_back_to_path(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": None, "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f))
+        # null project is treated the same as absent — path derivation runs.
+        assert state.source_named[name] is False
+
+    def test_explicit_name_param_beats_project_field(self, tmp_path):
+        f = tmp_path / "traces.jsonl"
+        self._write_traces(f, [{"project": "agora", "action": "test"}])
+        state = ViewerState()
+        name = state.add_source(str(f), name="override")
+        assert name == "override"
+        assert state.source_named[name] is True
+
+    def test_directory_source_reads_project_from_first_file(self, tmp_path):
+        (tmp_path / "a.jsonl").write_text(
+            _json.dumps({"project": "myapp", "action": "x"}) + "\n"
+        )
+        state = ViewerState()
+        name = state.add_source(str(tmp_path))
+        assert name == "myapp"
+        assert state.source_named[name] is True
+
+    def test_collision_suffix_applied_to_project_name(self, tmp_path):
+        f1 = tmp_path / "a.jsonl"
+        f2 = tmp_path / "b.jsonl"
+        self._write_traces(f1, [{"project": "agora"}])
+        self._write_traces(f2, [{"project": "agora"}])
+        state = ViewerState()
+        n1 = state.add_source(str(f1))
+        n2 = state.add_source(str(f2))
+        assert n1 == "agora"
+        assert n2 == "agora-2"

{traceact-0.6.2 → traceact-0.8.0}/traceact/__init__.py

@@ -70,7 +70,7 @@
 #   TraceActASGIMiddleware — ASGI middleware (FastAPI, Starlette). Same as
 #                   above for async frameworks.
 
-__version__ = "0.6.2"
+__version__ = "0.8.0"
 
 from traceact.config import configure, reset_config, TraceConfig
 from traceact.budget import TraceBudget

{traceact-0.6.2 → traceact-0.8.0}/traceact/config.py

@@ -149,12 +149,14 @@ class TraceConfig:
 _package_config: Optional[TraceConfig] = None
 _package_budget: Any = None          # Optional[TraceBudget] — typed as Any to avoid circular import
 _package_sinks: List[Any] = []       # List[Sink]
+_package_project: Optional[str] = None  # set via configure(project=...); stamped onto every trace
 
 
 def configure(
     config: Optional[TraceConfig] = None,
     budget: Any = None,
     sinks: Optional[List[Any]] = None,
+    project: Optional[str] = None,
 ) -> None:
     """
     Set package-wide defaults for all future traces.
@@ -163,20 +165,25 @@ def configure(
     baseline for every trace unless a specific trace or decorator overrides them.
 
     Args:
-        config:  A TraceConfig instance. Only non-None fields are applied; the
-                 rest keep their current values (or package defaults).
-        budget:  A TraceBudget instance. Only non-None fields are applied.
-        sinks:   A list of sink objects (JsonlSink, ConsoleSink, etc.). Replaces
-                 the current sink list entirely.
+        config:   A TraceConfig instance. Only non-None fields are applied; the
+                  rest keep their current values (or package defaults).
+        budget:   A TraceBudget instance. Only non-None fields are applied.
+        sinks:    A list of sink objects (JsonlSink, ConsoleSink, etc.). Replaces
+                  the current sink list entirely.
+        project:  The application or project name. Stamped onto every trace so
+                  the viewer can label sources by their project rather than by
+                  the sink's file path. Required in practice — traces written
+                  without a project name emit a warning.
 
     Example:
         configure(
+            project="my-app",
             config=TraceConfig(enabled=True, sink_mode="buffered"),
             budget=TraceBudget(max_events=200),
             sinks=[JsonlSink("traces.jsonl")],
         )
     """
-    global _package_config, _package_budget, _package_sinks
+    global _package_config, _package_budget, _package_sinks, _package_project
 
     if config is not None:
         _package_config = config
@@ -187,6 +194,9 @@ def configure(
     if sinks is not None:
         _package_sinks = list(sinks)
 
+    if project is not None:
+        _package_project = project
+
 
 def reset_config() -> None:
     """
@@ -207,11 +217,18 @@ def reset_config() -> None:
         - Traces that have already been written to a sink. Those are gone.
         - Files on disk. JsonlSink output is not deleted.
     """
-    global _package_config, _package_budget, _package_sinks
+    global _package_config, _package_budget, _package_sinks, _package_project
 
     _package_config = None
     _package_budget = None
     _package_sinks = []
+    _package_project = None
+
+    # Discard any buffered records so one test's buffered traces cannot leak
+    # into the next test's buffer state. Imported here to avoid a circular
+    # import at module load time (sinks.py does not import config.py).
+    from traceact.sinks import reset_buffer
+    reset_buffer()
 
     # Clear the active trace context so tests start with a clean slate.
     # The deferred import avoids a circular dependency at module load time
@@ -244,3 +261,8 @@ def get_package_budget() -> Any:
 def get_package_sinks() -> List[Any]:
     """Return the current list of configured sinks."""
     return _package_sinks
+
+
+def get_package_project() -> Optional[str]:
+    """Return the package-level project name, or None if not set."""
+    return _package_project

{traceact-0.6.2 → traceact-0.8.0}/traceact/sinks.py

@@ -76,6 +76,21 @@ def _ensure_flush_registered() -> None:
         _flush_registered = True
 
 
+def reset_buffer() -> None:
+    """
+    Discard all buffered records and reset the atexit flush registration.
+
+    Call this in test teardown (via reset_config()) to prevent one test's
+    buffered traces from leaking into the next test's buffer state. Not
+    intended for production use — buffered records not yet flushed to a sink
+    are silently discarded.
+    """
+    global _flush_registered
+    with _buffer_lock:
+        _buffer.clear()
+    _flush_registered = False
+
+
 def buffer_record(record: Dict[str, Any]) -> None:
     """
     Add a finished trace record to the in-memory buffer.

{traceact-0.6.2 → traceact-0.8.0}/traceact/trace.py

@@ -40,10 +40,13 @@ from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional, Union
 
 from traceact.budget import BUDGET_DEFAULTS, TraceBudget
+import warnings
+
 from traceact.config import (
     TraceConfig,
     get_package_budget,
     get_package_config,
+    get_package_project,
     get_package_sinks,
 )
 from traceact.context import SKIP, get_active_trace, is_skip, pop_trace, push_trace
@@ -1047,6 +1050,17 @@ class ActionTrace(TraceHelpersMixin):
         if mode == "disabled":
             return
 
+        # Warn once when a root trace (no parent) is about to be written with no
+        # project set. Child traces are silent — the root already told them.
+        if self.project is None and self.parent_trace_id is None:
+            warnings.warn(
+                "TraceAct: trace written without a project name. "
+                "Add project='your-app' to your configure() call so the viewer "
+                "can label this source correctly.",
+                UserWarning,
+                stacklevel=2,
+            )
+
         sinks = get_package_sinks()
 
         # If no sinks have been configured, fall back to ConsoleSink so that
@@ -1231,11 +1245,18 @@ def _create_trace(
         return _NoOpTrace()
 
     # --- Create the real trace ---
+    # If the caller didn't specify a project, inherit from the package config,
+    # then from the parent trace. Package wins over parent so that a single
+    # configure(project=...) stamps every trace regardless of nesting depth.
+    resolved_project = project or get_package_project() or (
+        parent.project if parent is not None else None
+    )
+
     trace = ActionTrace(
         action=action,
         kind=kind,
         actor=actor,
-        project=project,
+        project=resolved_project,
         parent=parent,
         correlation_id=correlation_id,
         upstream_trace_id=upstream_trace_id,

{traceact-0.6.2 → traceact-0.8.0}/traceact/viewer/instance.py

@@ -96,6 +96,7 @@ def launch_or_connect(
     port: int = 8765,
     open_browser: bool = False,
     timeout: float = 3.0,
+    name: Optional[str] = None,
 ) -> str:
     """
     Ensure a viewer is running and return its URL.  Designed to be called from
@@ -126,6 +127,14 @@ def launch_or_connect(
     viewer opens on *that* source. Without it, the front-end selects whichever
     source is first in the list — so an app adding its source to a viewer
     another app had already started would open showing the other app's traces.
+
+    ``name`` labels this source in the viewer's picker. Leave it unset and the
+    viewer derives one from the path, skipping generic components so
+    ``~/Dev/agora/data/traces/traces.jsonl`` reads as "agora". Pass it when the
+    app knows its own name and shouldn't depend on where its files happen to
+    sit::
+
+        launch_or_connect(source="data/traces/traces.jsonl", name="agora")
     """
     import subprocess
     import sys
@@ -136,15 +145,17 @@ def launch_or_connect(
     if existing is not None:
         h, p = existing["host"], existing["port"]
         if source is not None:
-            added = add_source_to(h, p, source)
+            added = add_source_to(h, p, source, name=name)
             if added and added.get("name"):
                 return f"http://{h}:{p}/?source={quote(added['name'], safe='')}"
         return f"http://{h}:{p}/"
 
-    # Not running — start one in the background.
+    # Not running — start one in the background. A source is seeded on the
+    # command line only when no explicit name was given: the CLI path derives
+    # its own name, so a named source is added over HTTP once the server is up.
     cmd = [sys.executable, "-m", "traceact.viewer.cli", "view", "--no-browser",
            "--host", host, "--port", str(port)]
-    if source is not None:
+    if source is not None and name is None:
         cmd.append(source)
     subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
 
@@ -160,6 +171,10 @@ def launch_or_connect(
     # so the URL stays correct if another app adds a source before the tab
     # is opened.
     if source is not None:
+        if name is not None:
+            added = add_source_to(host, port, source, name=name)
+            if added and added.get("name"):
+                return f"http://{host}:{port}/?source={quote(added['name'], safe='')}"
         names = list_source_names(host, port)
         if names:
             return f"http://{host}:{port}/?source={quote(names[0], safe='')}"
@@ -167,13 +182,21 @@ def launch_or_connect(
 
 
 def add_source_to(host: str, port: int, path: str,
-                  timeout: float = 1.0) -> Optional[dict]:
+                  timeout: float = 1.0,
+                  name: Optional[str] = None) -> Optional[dict]:
     """
     Ask an already-running viewer to add a source. Returns the created source
     ({name, path}) or None on failure.
+
+    ``name`` labels the source explicitly; without it the viewer derives one
+    from the path. Note the viewer dedupes by path, so a path it already knows
+    keeps the name it was first registered under.
     """
     url = f"http://{host}:{port}/api/sources"
-    data = json.dumps({"path": path}).encode("utf-8")
+    payload = {"path": path}
+    if name is not None:
+        payload["name"] = name
+    data = json.dumps(payload).encode("utf-8")
     req = urllib.request.Request(
         url, data=data,
         headers={"Content-Type": "application/json"}, method="POST",

{traceact-0.6.2 → traceact-0.8.0}/traceact/viewer/server.py

@@ -112,14 +112,19 @@ class ViewerState:
 
     def __init__(self) -> None:
         self.sources: Dict[str, str] = {}
+        # True when the name came from the project field in the trace data,
+        # False when it was derived from the file path. Used by the viewer to
+        # flag unnamed sources so developers know to set configure(project=...).
+        self.source_named: Dict[str, bool] = {}
 
     def add_source(self, path: str, name: Optional[str] = None) -> str:
         """
         Register a source and return the name it was stored under.
 
-        If no name is given, one is derived from the path: the folder name for a
-        directory, or the file's stem for a file. Collisions get a numeric
-        suffix so two files with the same name stay distinct.
+        If no name is given, the project field from the first trace record is
+        used. Falls back to _derive_name() (path-based) when no project is
+        set. Collisions still get a numeric suffix so two distinct paths stay
+        distinguishable.
 
         Adding a path that is already registered returns the existing name
         rather than registering it again — an app that calls
@@ -130,10 +135,20 @@ class ViewerState:
         for existing_name, existing_path in self.sources.items():
             if existing_path == path:
                 return existing_name
+        named = False
         if name is None:
-            name = _derive_name(path)
+            project = _read_project_from_source(path)
+            if project:
+                name = project
+                named = True
+            else:
+                name = _derive_name(path)
+        else:
+            # Caller supplied an explicit name (e.g. launch_or_connect(name=...)).
+            named = True
         name = self._unique_name(name)
         self.sources[name] = path
+        self.source_named[name] = named
         return name
 
     def _unique_name(self, name: str) -> str:
@@ -284,9 +299,14 @@ class _Handler(BaseHTTPRequestHandler):
     # -- sources API -------------------------------------------------------
 
     def _serve_sources(self) -> None:
+        state = self.server.state  # type: ignore[attr-defined]
         payload = [
-            {"name": name, "path": path}
-            for name, path in self.server.state.sources.items()  # type: ignore[attr-defined]
+            {
+                "name": name,
+                "path": path,
+                "named": state.source_named.get(name, False),
+            }
+            for name, path in state.sources.items()
         ]
         self._send_json(200, payload)
 
@@ -298,9 +318,12 @@ class _Handler(BaseHTTPRequestHandler):
         name = self.server.state.add_source(  # type: ignore[attr-defined]
             body["path"], body.get("name")
         )
-        self._send_json(
-            200, {"name": name, "path": self.server.state.sources[name]}  # type: ignore[attr-defined]
-        )
+        state = self.server.state  # type: ignore[attr-defined]
+        self._send_json(200, {
+            "name": name,
+            "path": state.sources[name],
+            "named": state.source_named.get(name, False),
+        })
 
     # -- SSE stream --------------------------------------------------------
 
@@ -495,12 +518,95 @@ def _pick_via_tkinter(pick_type: str) -> Optional[str]:
         return None
 
 
+# Path components that say where traces live, not which project they belong
+# to. Almost every app writes to some variation of <project>/data/traces/
+# traces.jsonl, so naming a source after any of these makes every project's
+# source read the same — "traces", "traces-2", "traces-3" — which is the one
+# thing the name has to distinguish.
+_GENERIC_PATH_NAMES = frozenset({
+    "traces", "trace", "tracing", "traceact",
+    "logs", "log", "logging",
+    "data", "output", "outputs", "out", "results",
+    "var", "tmp", "temp", "cache",
+    "run", "runs", "instrumentation", "telemetry",
+})
+
+
+def _is_generic_component(component: str) -> bool:
+    """True if a path component describes storage rather than a project."""
+    return component.lower().lstrip(".") in _GENERIC_PATH_NAMES
+
+
+def _read_project_from_source(path: str) -> Optional[str]:
+    """
+    Return the ``project`` field from the first trace record in a source, or
+    None if the source is empty, unreadable, or the field is absent/null.
+
+    For a directory source, the first lexicographically-sorted .jsonl file is
+    checked. This keeps the lookup O(1) in the common case — we only ever read
+    one line from one file.
+    """
+    try:
+        if os.path.isdir(path):
+            files = sorted(
+                f for f in os.listdir(path) if f.endswith(".jsonl")
+            )
+            if not files:
+                return None
+            target = os.path.join(path, files[0])
+        else:
+            target = path
+
+        with open(target, encoding="utf-8") as fh:
+            line = fh.readline()
+        if not line.strip():
+            return None
+        record = json.loads(line)
+        return record.get("project") or None
+    except Exception:
+        return None
+
+
 def _derive_name(path: str) -> str:
-    """Human-friendly source name from a path: folder name, or file stem."""
+    """
+    Derive a source name that identifies the project, not the storage layout.
+
+    Two rules, in order:
+
+    1. If the file's own name is specific (``agora_traces.jsonl``), use it.
+       An app that already names its trace files per project gets that name
+       honoured as-is.
+
+    2. Otherwise walk up the directory chain and use the first component that
+       isn't generic, so ``~/Dev/agora/data/traces/traces.jsonl`` becomes
+       "agora" rather than "traces". Without this every project on a machine
+       lands on the same name and the source picker can't tell them apart.
+
+    A shard or rotation suffix (``traces.1234.jsonl``,
+    ``traces.20260726T120000000000Z.jsonl``) reduces to its first segment, so
+    every shard of one project derives the same project name.
+
+    Falls back to "source" when every component is generic. Callers that know
+    better can always pass an explicit name (see ViewerState.add_source and
+    launch_or_connect(name=...)).
+    """
+    path = os.path.normpath(path)
+    parts = [p for p in path.split(os.sep) if p]
+
     if os.path.isdir(path):
-        return os.path.basename(os.path.normpath(path)) or "source"
-    stem = os.path.splitext(os.path.basename(path))[0]
-    return stem or "source"
+        candidates = parts
+    else:
+        stem = os.path.splitext(parts[-1])[0] if parts else ""
+        # "traces.1234" / "traces.<timestamp>" → "traces"
+        base = stem.split(".")[0]
+        if base and not _is_generic_component(base):
+            return base.lstrip(".")
+        candidates = parts[:-1]
+
+    for component in reversed(candidates):
+        if not _is_generic_component(component):
+            return component.lstrip(".") or "source"
+    return "source"
 
 
 def _parse_query_filters(query: Dict[str, list]) -> Dict[str, Any]:

{traceact-0.6.2 → traceact-0.8.0}/traceact/viewer/static/app.js

@@ -17,7 +17,7 @@
  *   never grows unbounded no matter how busy the source is. */
 
 const state = {
-  sources: [],            // [{name, path}]
+  sources: [],            // [{name, path, named}] — named=false means project field was absent
   currentSource: null,    // source name currently streamed
   traces: [],             // newest-first, capped at settings.limit
   selected: null,         // the trace object shown in the inspector
@@ -1129,13 +1129,25 @@ function closeModal() {
 function renderSourceList() {
   const list = document.getElementById("source-list");
   if (!list) return;
+
+  // The list scrolls once it outgrows its panel, so the count is the only
+  // cue to how many sources are off-screen.
+  const label = document.getElementById("source-list-label");
+  if (label) {
+    label.textContent = state.sources.length > 0
+      ? `SOURCES (${state.sources.length})`
+      : "SOURCES";
+  }
+
   if (state.sources.length === 0) {
     list.innerHTML = `<div class="muted" style="padding:6px 0">No sources yet.</div>`;
     return;
   }
   list.innerHTML = state.sources.map((s) => `
     <div class="source-option" data-name="${esc(s.name)}">
-      <div class="name">${esc(s.name)}</div>
+      <div class="name">
+        ${esc(s.name)}${s.named ? "" : ' <span class="unnamed-badge" title="No project name set — add configure(project=&quot;your-app&quot;) to your traceact setup">unnamed</span>'}
+      </div>
       <span class="path-chip">
         <div class="path">${esc(shortenPath(s.path))}</div>
         <button class="path-copy-btn" data-full="${esc(s.path)}"

{traceact-0.6.2 → traceact-0.8.0}/traceact/viewer/static/index.html

@@ -189,7 +189,7 @@
   <!-- Add-source modal -->
   <div class="modal-backdrop" id="source-modal" hidden>
     <div class="modal">
-      <div class="modal-section-label">SOURCES</div>
+      <div class="modal-section-label" id="source-list-label">SOURCES</div>
       <div id="source-list"></div>
 
       <div class="modal-section-label">ADD SOURCE</div>

{traceact-0.6.2 → traceact-0.8.0}/traceact/viewer/static/styles.css

@@ -654,7 +654,35 @@ body {
   border: 1px solid var(--border-strong);
   border-radius: 10px;
   padding: 16px;
+  /* Cap the whole modal so it can't outgrow the viewport on a short window;
+     the source list below is the part that scrolls. */
+  max-height: 82vh;
+  overflow-y: auto;
+}
+
+/* The source list scrolls inside its own area rather than stretching the
+   modal: a dev machine can accumulate a source per project, and an unbounded
+   list would push the "add source" controls off-screen. ~5 rows stay visible;
+   the rest are one scroll away.
+
+   The inset panel treatment matters as much as the max-height — without a
+   visible boundary, a row clipped mid-text at the scroll edge reads as a
+   rendering fault rather than "there is more below". */
+#source-list {
+  max-height: 244px;
+  overflow-y: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--bg-panel);
+  padding: 4px;
 }
+#source-list::-webkit-scrollbar { width: 8px; }
+#source-list::-webkit-scrollbar-track { background: transparent; }
+#source-list::-webkit-scrollbar-thumb {
+  background: var(--border-strong);
+  border-radius: 4px;
+}
+#source-list::-webkit-scrollbar-thumb:hover { background: var(--text-faint); }
 .modal-section-label {
   color: var(--text-faint);
   font-size: 10.5px;
@@ -676,6 +704,19 @@ body {
 /* .path-chip defaults to inline-flex for the header's inline usage; here it
    needs to sit on its own line under .name, so it takes the block it replaced. */
 .source-option .path-chip { display: flex; align-items: center; }
+.unnamed-badge {
+  display: inline-block;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  padding: 1px 5px;
+  border-radius: 3px;
+  background: var(--bg-hover);
+  color: var(--text-faint);
+  border: 1px solid var(--border);
+  vertical-align: middle;
+  margin-left: 5px;
+}
 
 /* Drop zone */
 .drop-zone {

{traceact-0.6.2 → traceact-0.8.0/traceact.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceact
-Version: 0.6.2
+Version: 0.8.0
 Summary: X-ray vision for your code. Lightweight action-level tracing for Python.
 Author: Mohammed Shehu
 License-Expression: MIT
@@ -55,6 +55,7 @@ pip install traceact
 from traceact import traced_action, configure, TraceConfig, JsonlSink
 
 configure(
+    project="my-app",
     config=TraceConfig(sink_mode="blocking"),
     sinks=[JsonlSink("data/traces.jsonl")],
 )

{traceact-0.6.2 → traceact-0.8.0}/traceact.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ tests/test_decorators.py
 tests/test_doctor.py
 tests/test_http_sink.py
 tests/test_otlp_sink.py
+tests/test_project_name.py
 tests/test_propagation.py
 tests/test_reader.py
 tests/test_redaction.py