f

Author: sashwinbalaji

CHANGELOG

@@ -15,10 +15,11 @@ Unreleased:
   SDK:
     *
   Tools:
-    * tracebox: Added `tracebox ctl` applet for explicit daemon lifecycle
-      management (start/stop/status). Default behavior now requires daemons
-      to be running on Linux/macOS. Use `tracebox ctl start` to manage
-      persistent daemons or `--autodaemonize` for legacy self-contained mode.
+    * Breaking change for tracebox users: `tracebox` no longer automatically
+      starts daemons by default. Daemons must be running before capturing a
+      trace. We recommend using the new `tracebox ctl` applet (e.g. `tracebox
+      ctl start`) to manage persistent daemons. To restore the previous
+      self-contained behavior, use the `--legacy` flag.
 
 v53.0 - 2025-11-12:
   SDK:

docs/getting-started/cpu-profiling.md

@@ -163,6 +163,7 @@ echo -1 | sudo tee /proc/sys/kernel/perf_event_paranoid
 Assuming the example config above is saved as `/tmp/config.txtpb`, start the
 recording.
 ```bash
+./tracebox ctl start
 ./tracebox -c /tmp/config.txtpb --txt -o /tmp/trace.pb
 ```
 
@@ -333,6 +334,7 @@ Assuming the example config above is saved as `/tmp/config.txtpb` (with the
 target\_cmdline option changed to a process on your machine), start the
 recording.
 ```bash
+./tracebox ctl start
 ./tracebox -c /tmp/config.txtpb --txt -o /tmp/trace.pb
 ```
 

docs/getting-started/ftrace.md

@@ -285,9 +285,15 @@ See the [system tracing page](/docs/getting-started/system-tracing.md) in order
 to get set up with tracebox. For this example we are going to record a trace
 from the command line using the config file we just created:
 ```bash
+./tracebox ctl start
 ./tracebox -c ticker.cfg --txt -o ticker.pftrace
 ```
 
+Alternatively using legacy mode:
+```bash
+./tracebox --legacy -c ticker.cfg --txt -o ticker.pftrace
+```
+
 Note: tracebox will take care of enabling tracing and our ticker events (as we
 did manually in the preceding step).
 

docs/getting-started/memory-profiling.md

@@ -174,15 +174,20 @@ chmod +x tracebox heap_profile
 
 Start the tracing service
 ```bash
-./tracebox traced &
+./tracebox ctl start
 ```
 
 Generate the heapprofd config and start the tracing session.
 ```bash
 # Replace trace_processor_shell with with the name of the process you want to
 # profile.
 ./heap_profile -n trace_processor_shell --print-config | \
-  ./tracebox perfetto --txt -c - -o ~/trace_processor_memory.pftrace
+  ./tracebox -c - --txt -o ~/trace_processor_memory.pftrace
+```
+Alternatively, use the legacy self-contained mode (no `ctl start` required):
+```bash
+./heap_profile -n trace_processor_shell --print-config | \
+  ./tracebox --legacy -c - --txt -o ~/trace_processor_memory.pftrace
 ```
 
 Open another terminal (or tab), start the process you want to profile,
@@ -213,10 +218,9 @@ In either case: press Ctrl-C on the `tracebox perfetto` command of the previous
 step. That will write the trace file (e.g. `~/trace_processor_memory.pftrace`)
 which you can then open with the Perfetto UI.
 
-Remember also to kill the `tracebox traced` service once you are done.
+Remember also to kill the `tracebox` services once you are done.
 ```bash
-fg
-# Ctrl-C
+./tracebox ctl stop
 ```
 </tabs?>
 

docs/getting-started/system-tracing.md

@@ -153,7 +153,13 @@ chmod +x tracebox
 
 ## Capturing a trace
 
-To capture a trace you need to pass the config file to the downloaded `tracebox`
+First, start the tracing daemons in background:
+
+```bash
+./tracebox ctl start
+```
+
+Then, to capture a trace you need to pass the config file to the downloaded `tracebox`
 binary. We have some sample config files in the [/test/configs/](/test/configs/)
 directory.
 Lets say you want to capture a trace with the scheduling information. You can
@@ -166,7 +172,12 @@ and running the following command:
 ./tracebox -o trace_file.perfetto-trace --txt -c scheduling.cfg
 ```
 The scheduling information is captured using ftrace, so you may need to start
-the `tracebox` with root privileges.
+the `tracebox` daemons with root privileges (e.g. `sudo ./tracebox ctl start`).
+
+If you prefer the old behavior where tracebox starts temporary daemons for the duration of the trace, you can use the `--legacy` flag:
+```bash
+./tracebox --legacy -o trace_file.perfetto-trace --txt -c scheduling.cfg
+```
 
 </tabs?>
 

docs/learning-more/tracing-in-background.md

@@ -23,6 +23,8 @@ that no data is lost at the beginning of the trace.
 Start recording a trace using `tracebox` or `perfetto`.
 
 ```bash
+# If using tracebox, ensure daemons are started first:
+# tracebox ctl start
 perfetto -c config.cfg --txt -o trace.pftrace --background-wait
 ```
 

docs/reference/tracebox.md

@@ -13,7 +13,7 @@ tracebox -t 10s -o trace.pftrace sched freq
 tracebox ctl stop
 
 # Self-contained mode (legacy)
-tracebox --autodaemonize -t 10s -o trace.pftrace sched
+tracebox --legacy -t 10s -o trace.pftrace sched
 
 # Invoke bundled applets
 tracebox [applet_name] [args ...]
@@ -25,9 +25,15 @@ tracebox [applet_name] [args ...]
 (`traced_probes`), and the `perfetto` command-line client into a single binary.
 
 **Behavior change (2025):** `tracebox` now requires daemons to be running before
-capturing traces. Use `tracebox ctl` to manage daemons, or `--autodaemonize` for
+capturing traces. Use `tracebox ctl` to manage daemons, or `--legacy` for
 the legacy self-contained mode.
 
+If you are a user of `tracebox` in its default mode (i.e., you don't use
+`--legacy`), you should read the migration guide below. The new default
+behavior provides a more robust and predictable experience, especially for
+processes instrumented with the Perfetto SDK, but it requires a small change to
+your workflow.
+
 ## DAEMON MANAGEMENT
 
 ### tracebox ctl start [--log]
@@ -68,18 +74,29 @@ If systemd service files are detected:
 - As root: `ctl start` uses `systemctl start traced traced-probes`
 - As user: Instructs to use `sudo systemctl start traced traced-probes`
 
-## SELF-CONTAINED MODE
+## LEGACY SELF-CONTAINED MODE
+
+The `--legacy` flag preserves the legacy behavior of `tracebox` where it
+spawns temporary daemons for the duration of a single trace session. This mode
+uses private, temporary sockets and is fully self-contained.
 
-The `--autodaemonize` flag spawns temporary daemons for a single trace session.
+**When to use:**
+- For quick one-off traces where you don't want to manage daemons.
+- If you cannot or do not want to run persistent background daemons.
+- For scripts that rely on the old behavior and haven't been migrated yet.
 
 **Limitations:**
-- SDK-instrumented apps won't connect (uses private sockets)
-- Inefficient for multiple traces
-- Not recommended for regular use
+- **SDK Incompatibility:** Processes instrumented with the Perfetto SDK (e.g.
+  using `track_event`) will generally fail to connect to these temporary daemons
+  because they listen on private, unpredictable socket addresses.
+- **Inefficiency:** Spawns and kills daemons for every trace, which is slower
+  for repeated tracing.
+- **Concurrency:** Running multiple instances of `tracebox --legacy`
+  concurrently can lead to resource conflicts (e.g. with ftrace).
 
 **Example:**
 ```bash
-tracebox --autodaemonize -t 10s -o trace.pftrace sched freq
+tracebox --legacy -t 10s -o trace.pftrace sched freq
 ```
 
 ## APPLET MODE
@@ -113,7 +130,7 @@ tracebox ctl status  # Check daemon status
 
 If daemons aren't running:
 - Use `tracebox ctl start` to start them
-- Or use `--autodaemonize` for self-contained mode
+- Or use `--legacy` for self-contained mode
 
 ### Permission denied
 
@@ -141,23 +158,56 @@ sudo systemctl stop traced traced-probes
 tracebox ctl start
 ```
 
-## MIGRATION
-
-**Old (before 2025):**
-```bash
-tracebox -t 10s -o trace.pftrace sched
-```
-
-**New (recommended):**
-```bash
-tracebox ctl start
-tracebox -t 10s -o trace.pftrace sched
-```
-
-**New (backward compatible):**
-```bash
-tracebox --autodaemonize -t 10s -o trace.pftrace sched
-```
+## MIGRATION GUIDE (2025)
+
+The default behavior of `tracebox` has changed to require explicit daemon
+management. This change resolves long-standing issues with SDK connectivity and
+provides a more consistent experience.
+
+### Why the change?
+In the old model, `tracebox` would silently spawn "ephemeral" daemons on private
+sockets. This often confused users because apps instrumented with the Perfetto
+SDK (e.g., Chrome, or your own apps) would fail to connect to these hidden
+daemons, resulting in traces missing all userspace data. The new model ensures
+daemons run on standard system sockets where SDK apps can find them.
+
+### Migration Steps
+
+**Scenario 1: You run interactive traces manually**
+
+*   **Old way:**
+    ```bash
+    tracebox -t 10s -o trace.pftrace sched
+    ```
+*   **New way (Recommended):**
+    Run this once per boot (or when needed):
+    ```bash
+    tracebox ctl start
+    ```
+    Then run your traces as usual:
+    ```bash
+    tracebox -t 10s -o trace.pftrace sched
+    ```
+    When done (optional):
+    ```bash
+    tracebox ctl stop
+    ```
+
+**Scenario 2: You have scripts that wrap tracebox**
+
+*   **Option A (Better):** Update your scripts to ensure daemons are running
+    using `tracebox ctl start` before tracing.
+*   **Option B (Faster fix):** Update your scripts to use the `--legacy`
+    flag to restore the old behavior.
+    ```bash
+    tracebox --legacy -t 10s -o trace.pftrace sched
+    ```
+
+**Scenario 3: You are tracing SDK-instrumented apps**
+
+You **must** use the new explicit daemon mode. The legacy `--legacy` mode
+will likely not work because your app won't be able to discover the temporary
+sockets.
 
 ## SEE ALSO