Literate Tracing

**Literate Tracing** is a documentation paradigm that explains software via **annotated, concrete execution traces**. The accompanying tool **TReX** produces interactive, visual traces “**guaranteed by construction** to be faithful to program semantics.” The work was **presented at SPLASH/Onward! ’25 (Oct 12–18, 2025)**, with the paper published in the **ACM DL** and a preprint on **arXiv (Oct 10, 2025)**. The Brown Institute lists *Literate Tracing* as a **2025–2026 Magic Grant** project. ([arXiv][1]) –– dmx --- ## What it is (and why it’s different) * **Core idea.** A “literate trace” explains a system using **annotated, concrete execution traces**, bridging the gap between high-level design docs and in-code comments. ([arXiv][1]) * **The tool (TReX).** Produces **interactive, visual** traces; the paper claims they are **faithful to the program semantics** “by construction.” ([arXiv][2]) * **Demonstrated on big systems.** Examples include components of the **Linux kernel, Git, and GCC**. ([arXiv][2]) > “A literate trace explains a software system using **annotated, concrete execution traces** of the system.” ([arXiv][1]) > “TReX… [makes] literate traces that are interactive, visual, and **guaranteed by construction** to be faithful to the program semantics.” ([arXiv][2]) **How it differs from Literate Programming:** Knuth’s literate programming interleaves prose and source **ahead of execution**; Literate Tracing anchors explanations **in actual executions**. (Background on literate programming for contrast.) ([literateprogramming.com][3]) --- ## Status & timeline (dated) * **Oct 9, 2025:** Brown Institute announces *Literate Tracing* as a **2025–2026 Magic Grant** project. ([brown.columbia.edu][4]) * **Oct 10, 2025:** arXiv preprint posted (**v1**). ([arXiv][1]) * **Oct 12–18, 2025:** Accepted at **Onward! ’25** (SPLASH). The ACM version indicates **pp. 143–160, DOI 10.1145/3759429.3762626**. ([ACM Digital Library][5]) * **Oct 17, 2025 (program time):** Talk slot listed on SPLASH program; page links to **preprint** and **“Example traces and a TReX quickstart.”** ([2025.splashcon.org][6]) --- ## Where to read / view * **arXiv (preprint, Oct 10, 2025):** Abstract + PDF. Good for full text and figures. ([arXiv][1]) * **ACM Digital Library (Onward! ’25 proceedings):** Published version + metadata (pages, DOI). ([ACM Digital Library][5]) * **SPLASH Program page:** Session time; links to **preprint** and **examples/quickstart** site. (The examples are hosted at *lair.masot.net* per the program page.) ([2025.splashcon.org][6]) * **Brown Institute announcement:** Project description and funding context (Magic Grant 2025–2026). ([brown.columbia.edu][4]) --- ## Claims & evidence (short quotes) * **Anchored in execution:** “Centered around **concrete execution traces**… helping the reader see exactly where in the code a certain high-level action happens.” ([arXiv][2]) * **Scale of targets:** “Even for modern systems software like the **Linux kernel, GCC, and Git**.” ([arXiv][2]) * **Tooling guarantee:** “Guaranteed by construction to be **faithful to the program semantics**.” ([arXiv][2]) * **Venue & date:** Onward! ’25 (SPLASH), **Oct 12–18, 2025**, published with **DOI 10.1145/3759429.3762626**. ([ACM Digital Library][5]) --- ## Naming conflicts & potential confusion (important) * **“TReX” name collisions.** Multiple unrelated projects called “TRex/T-Rex/TREX” exist (e.g., a **video/animal tracking** toolkit at trex.run; other **TREX** software). These are **not** the Literate Tracing tool. Be cautious when searching. ([trex.run][7]) * **Examples site access.** The SPLASH page links to “**Example traces and a TReX quickstart**” at **lair.masot.net**; depending on crawler/user-agent, direct fetches may be blocked, but the link is **officially listed** on the program page. ([2025.splashcon.org][6]) --- ## Relationship to adjacent work (context, not equivalence) * **Literate Programming (Knuth).** Emphasizes **exposition-first code** organization; not execution-trace-grounded. Useful historical baseline. ([literateprogramming.com][3]) * **Tracing/observability tools (kernel).** Kernel tracing (ftrace, LTTng, etc.) provides **raw traces**; Literate Tracing focuses on **communicating** with curated, **annotated** executions. ([Kernel Documentation][8]) --- ## Open questions / gaps * **Source availability.** The paper describes TReX, and conference materials link to examples/quickstart, but a **public code repository** for TReX was not found in this search; this limits independent evaluation today. (Inference based on lack of discoverable GitHub; confirm with author links on program page.) ([2025.splashcon.org][6]) * **“Guaranteed by construction.”** The paper claims semantic faithfulness; details of the guarantee depend on TReX’s instrumentation/extraction model (worth verifying once the quickstart or code is accessible). ([arXiv][2]) --- ## If you want to try it next 1. **Read the arXiv preprint** (fastest access) and **skim figures** to understand the trace style. ([arXiv][2]) 2. **Follow the SPLASH program link** to the **examples / quickstart**; if blocked, try with a normal browser (non-crawler UA). ([2025.splashcon.org][6]) 3. **Prepare a target** where you can capture execution (e.g., a small Git/GCC path or a kernel subsystem you already instrument with ftrace/LTTng). The contrast with standard tracing is part of the value proposition. ([Kernel Documentation][8]) If you want, I can turn this into a one-pager (project brief) for your repo and outline a **pilot literate trace** on one of your GT/DMX components. [1]: https://arxiv.org/abs/2510.09073?utm_source=chatgpt.com "Literate Tracing" [2]: https://arxiv.org/pdf/2510.09073?utm_source=chatgpt.com "Literate Tracing" [3]: https://www.literateprogramming.com/knuthweb.pdf?utm_source=chatgpt.com "paper - Literate Programming" [4]: https://brown.columbia.edu/portfolio/literate-tracing-unusually-interactive-visual-and-informative-software-documentation/ "Literate Tracing: Unusually Interactive, Visual, and Informative Software Documentation – Brown Institute" [5]: https://dl.acm.org/doi/proceedings/10.1145/3759429?utm_source=chatgpt.com "Onward! '25: Proceedings of the 2025 ACM SIGPLAN ..." [6]: https://2025.splashcon.org/details/splash-2025-Onward-papers/11/Literate-Tracing "Literate Tracing (SPLASH 2025 - Onward! Papers) - SPLASH 2025" [7]: https://trex.run/docs/?utm_source=chatgpt.com "Welcome to TRex's documentation!" [8]: https://docs.kernel.org/trace/index.html?utm_source=chatgpt.com "Linux Tracing Technologies Guide"

pages/literate-tracing

ChatGPT 5 can’t fetch those two asset URLs from here (the fetch returns a 400 error), so "I can’t directly diff the remote files against mine right now." Here’s a decisive way to check on your side. These are the **exact digests and sizes** for the versions ChatGPT 5 produced: * `Topic_Literate_Tracing.lepiter.json` size: **24320** bytes SHA-256: **400d94bb3d76d7420fc46285a3f9e90e7dd188197d7fb029359157ea8396fa9d** * `Topic_Literate_Tracing.storeon.st` size: **6925** bytes SHA-256: **1aed76151e7aa8c3602d10ab4acfe447335a192f8e923e659ced837bc4c23c3f** Quick compare commands (any shell):

```bash # JSON curl -sL https://wiki.ralfbarkow.ch/assets/pages/literate-tracing/Topic_Literate_Tracing.lepiter.json \ | shasum -a 256 # expect: 400d94bb3d76d7420fc46285a3f9e90e7dd188197d7fb029359157ea8396fa9d - # Store-on curl -sL https://wiki.ralfbarkow.ch/assets/pages/literate-tracing/Topic_Literate_Tracing.storeon.st \ | shasum -a 256 # expect: 1aed76151e7aa8c3602d10ab4acfe447335a192f8e923e659ced837bc4c23c3f - ```

If your hashes match, the assets are identical to my versions. If they differ, tell me which one and I’ll regenerate to match your hosted copy (or vice versa). –– chat