traceloom 0.1.0__tar.gz

traceloom-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+# Rulesets are hashed over raw bytes; pin LF so git clients cannot change
+# the SHA-256 of a checked-out ruleset file.
+native/data/*.tsv text eol=lf

traceloom-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+build/
+dist/
+*.egg-info/
+out/
+outputs/
+profiles/
+artifacts/
+reproduce/decode_a2a_buffer_reuse/local*.env
+*.db
+*.sqlite
+*.sqlite3
+!examples/kickstart_smoke/msprof_raw/PROF_*/msprof_*.db
+examples/kickstart_smoke/msprof_raw/traceloom/README.md
+examples/kickstart_smoke/msprof_raw/traceloom/meta.json
+**/traceloom/collective_summary.md
+*.nsys-rep
+*.qdrep
+*.qdstrm
+*.trace
+tmp/

traceloom-0.1.0/AGENTS.md

@@ -0,0 +1,68 @@
+# TraceLoom Agent Guide
+
+TraceLoom is a native C++17 offline profiler analyzer. Treat it as a
+post-processing tool, not as a runtime environment manager.
+
+## Primary Goal
+
+TraceLoom consumes accelerator profiler SQLite artifacts and emits a
+self-contained queryable database timeline. The production CLI is:
+
+```bash
+traceloom <profile.db-or-profile-dir>
+```
+
+Keep this entry point stable. Do not add alternate installed command names.
+
+## Build And Test
+
+```bash
+cmake --preset dev-tests
+cmake --build --preset dev-tests -j <chosen-jobs>
+ctest --preset dev-tests
+```
+
+Test a release build without the external fixture suite:
+
+```bash
+cmake -S native -B build/release \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DTRACELOOM_NATIVE_BUILD_TESTS=OFF
+cmake --build build/release -j <chosen-jobs>
+```
+
+Choose build parallelism from CPU affinity, cgroup quota, current load, and
+memory. On an otherwise idle host, use roughly half the affinity-available
+CPUs; do not let `OMP_NUM_THREADS` or plain container `nproc` silently reduce a
+large build to one job.
+
+## Analyze Existing Data
+
+```bash
+build/native-tests/native/traceloom /path/to/msprof_raw
+```
+
+Valid Ascend inputs include one schema-compatible profiler SQLite DB, such as
+`msprof_*.db` or the official torch-npu
+`ASCEND_PROFILER_OUTPUT/ascend_pytorch_profiler_*.db`, or a directory containing
+those monolithic DBs or split `PROF_*/{host,device_*}/sqlite/*.db` layouts. The
+default queryable database timeline is a neighboring
+`traceloom/analysis.db` or one `analysis_dbNN.db` per discovered analysis
+input. Markdown is an explicit human projection requested with
+`--loop-tree-out`.
+
+## Repository Hygiene
+
+Do not commit raw profiler databases, generated reports, local environments,
+model weights, or benchmark logs. Keep those in ignored build/output paths or
+external artifact storage.
+
+Before handing changes back:
+
+```bash
+git status --short
+ctest --preset dev-tests
+```
+
+Prefer nearby native APIs and structured SQLite access over ad hoc parsing.
+Keep edits scoped and preserve source-table/row provenance in new adapters.

traceloom-0.1.0/CMakeLists.txt

@@ -0,0 +1,7 @@
+cmake_minimum_required(VERSION 3.16)
+
+project(traceloom LANGUAGES CXX)
+
+enable_testing()
+
+add_subdirectory(native)

traceloom-0.1.0/CMakePresets.json

@@ -0,0 +1,59 @@
+{
+  "version": 3,
+  "configurePresets": [
+    {
+      "name": "dev",
+      "displayName": "TraceLoom native dev",
+      "generator": "Unix Makefiles",
+      "binaryDir": "${sourceDir}/build/native",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "CMAKE_PREFIX_PATH": "$env{HOME}/.local",
+        "TRACELOOM_NATIVE_BUILD_TESTS": "OFF",
+        "TRACELOOM_NATIVE_ENABLE_SQLITE_ADAPTERS": "ON"
+      }
+    },
+    {
+      "name": "dev-tests",
+      "displayName": "TraceLoom native dev with tests",
+      "inherits": "dev",
+      "binaryDir": "${sourceDir}/build/native-tests",
+      "cacheVariables": {
+        "TRACELOOM_NATIVE_BUILD_TESTS": "ON"
+      }
+    },
+    {
+      "name": "dev-no-sqlite",
+      "displayName": "TraceLoom native dev without SQLite",
+      "inherits": "dev",
+      "binaryDir": "${sourceDir}/build/native-no-sqlite",
+      "cacheVariables": {
+        "CMAKE_PREFIX_PATH": null,
+        "TRACELOOM_NATIVE_ENABLE_SQLITE_ADAPTERS": "OFF"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "dev",
+      "configurePreset": "dev"
+    },
+    {
+      "name": "dev-tests",
+      "configurePreset": "dev-tests"
+    },
+    {
+      "name": "dev-no-sqlite",
+      "configurePreset": "dev-no-sqlite"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "dev-tests",
+      "configurePreset": "dev-tests",
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}

traceloom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TraceLoom contributors
+
+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.

traceloom-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.2
+Name: traceloom
+Version: 0.1.0
+Summary: Native inference timeline analysis with a Python API and vLLM runtime observer
+Author: TraceLoom contributors
+License: MIT License
+         
+         Copyright (c) 2026 TraceLoom contributors
+         
+         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.
+         
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: Operating System :: POSIX :: Linux
+Project-URL: Homepage, https://github.com/vLLM-HUST/vllm-hust-perf-analyzer
+Project-URL: Documentation, https://github.com/vLLM-HUST/vllm-hust-perf-analyzer/blob/main/python/README.md
+Project-URL: Issues, https://github.com/vLLM-HUST/vllm-hust-perf-analyzer/issues
+Requires-Python: >=3.10
+Requires-Dist: traceloom-vllm-context==0.1.0
+Description-Content-Type: text/markdown
+
+# TraceLoom for Python
+
+**One installation for native timeline analysis, a Python interface, and the
+optional vLLM runtime observer.** The wheel includes the production C++17
+analyzer, default rule manifests, and model/step YAML configurations. It is not
+just a launcher for a separately installed executable.
+
+```sh
+python -m pip install traceloom==0.1.0
+traceloom /path/to/profile.db --output analysis.db
+```
+
+Python >=3.10. Linux wheels are platform-specific; source builds require C++17,
+CMake, SQLite and libyaml development libraries. Gzip Perfetto output additionally
+uses the system `gzip` executable. No torch, vLLM, or accelerator is needed for
+offline analysis. The small `traceloom-vllm-context` dependency supplies runtime
+observation; it does not install vLLM or change your serving environment.
+
+## Python analysis interface
+
+```python
+from pathlib import Path
+import traceloom
+
+# One profiler SQLite file. CLI directory discovery remains available separately.
+result = traceloom.analyze(
+    "profile.db",
+    output="analysis.db",
+    threads=4,
+    timeout=300,
+)
+rows = result.query(
+    "SELECT * FROM traceloom_v_position_occurrence WHERE position_id = ?",
+    ("node-N003",),
+)
+result.export_perfetto("timeline.perfetto.json.gz")
+
+# Reopen without re-running analysis.
+existing = traceloom.AnalysisDatabase(Path("analysis.db"))
+```
+
+`query()` uses a read-only SQLite connection, parameter binding and a default
+1,000-row limit. Larger results raise rather than silently truncate: narrow the
+query or set `limit=` explicitly. This is a local analysis API, not a service
+for arbitrary untrusted SQL. Native errors raise `traceloom.AnalysisError` with
+`returncode`, `command` and a bounded `diagnostic_tail`. Missing inputs, invalid
+arguments and `subprocess.TimeoutExpired` remain their ordinary Python types.
+The native process is isolated from the interpreter; structural recovery and
+source protection use exactly the same implementation as the CLI.
+
+## Runtime collection, then offline analysis
+
+In an existing compatible vLLM environment:
+
+```sh
+export TRACELOOM_CONTEXT_DIR=./traceloom-context
+export TRACELOOM_RUN_ID=inference-study-001
+vllm serve /path/to/model --async-scheduling \
+  --scheduler-cls traceloom.vllm.TracingAsyncScheduler
+```
+
+This patch-free entry records scheduler metadata only. It does **not** associate
+device execution. For that separate mode use `traceloom.vllm.LinkedTracingAsyncScheduler`
+plus the explicit `transport-worker.patch` from the
+[integration guide](https://github.com/vLLM-HUST/vllm-hust-perf-analyzer/blob/main/integrations/vllm/README.md).
+The original `traceloom_vllm_scheduler.*` class paths remain supported.
+Synchronous scheduling uses the corresponding `TracingScheduler` or
+`LinkedTracingScheduler` and omits `--async-scheduling`.
+
+After the ordinary profiler capture and context producers have closed:
+
+```python
+from pathlib import Path
+import traceloom
+
+result = traceloom.analyze(
+    "profile.db",
+    output="step-analysis.db",
+    context=sorted(Path("traceloom-context").glob("*.jsonl")),
+    rules_config=traceloom.bundled_rules("scheduler-step"),
+)
+result.export_perfetto("step-timeline.perfetto.json.gz")
+```
+
+Step-constrained recovery requires supported **execution-linked** evidence,
+not scheduler-only metadata. It currently supports eager grammar recovery, not
+protected replay or simultaneous marked-structure projection. Independently,
+`bundled_rules("deepseekv4")` provides model-unit hints; it is not automatic
+semantic inference for every model. Missing and ambiguous links remain explicit.
+
+The observer is experimental. Live collection validation is bounded to
+Qwen3-0.6B TP1/eager, in-process V1, vLLM `0fc695fc` and Ascend `f4a08bdd`.
+Different versions need source-contract checks. Graph/distributed collection,
+universal membership completeness and recording overhead are not qualified.
+Capturing metadata adds host work. The native analysis runs after capture, not
+inside the scheduler hot path. Restart without the custom scheduler class to
+remove the adapter; unset `TRACELOOM_CONTEXT_DIR` to disable recording.
+
+[Native analyzer and full documentation](https://github.com/vLLM-HUST/vllm-hust-perf-analyzer)
+· [MIT license](https://github.com/vLLM-HUST/vllm-hust-perf-analyzer/blob/main/LICENSE)