f

Author: sashwinbalaji

CHANGELOG

@@ -19,7 +19,7 @@ Unreleased:
       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.
+      self-contained behavior, use the `--autodaemonize` flag.
 
 v53.0 - 2025-11-12:
   SDK:

docs/getting-started/ftrace.md

@@ -289,9 +289,9 @@ from the command line using the config file we just created:
 ./tracebox -c ticker.cfg --txt -o ticker.pftrace
 ```
 
-Alternatively using legacy mode:
+Alternatively using autodaemonize mode:
 ```bash
-./tracebox --legacy -c ticker.cfg --txt -o ticker.pftrace
+./tracebox --autodaemonize -c ticker.cfg --txt -o ticker.pftrace
 ```
 
 Note: tracebox will take care of enabling tracing and our ticker events (as we

docs/getting-started/memory-profiling.md

@@ -184,10 +184,10 @@ Generate the heapprofd config and start the tracing session.
 ./heap_profile -n trace_processor_shell --print-config | \
   ./tracebox -c - --txt -o ~/trace_processor_memory.pftrace
 ```
-Alternatively, use the legacy self-contained mode (no `ctl start` required):
+Alternatively, use the autodaemonize mode (no `ctl start` required):
 ```bash
 ./heap_profile -n trace_processor_shell --print-config | \
-  ./tracebox --legacy -c - --txt -o ~/trace_processor_memory.pftrace
+  ./tracebox --autodaemonize -c - --txt -o ~/trace_processor_memory.pftrace
 ```
 
 Open another terminal (or tab), start the process you want to profile,

docs/getting-started/system-tracing.md

@@ -174,9 +174,9 @@ and running the following command:
 The scheduling information is captured using ftrace, so you may need to start
 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:
+If you prefer the old behavior where tracebox starts temporary daemons for the duration of the trace, you can use the `--autodaemonize` flag:
 ```bash
-./tracebox --legacy -o trace_file.perfetto-trace --txt -c scheduling.cfg
+./tracebox --autodaemonize -o trace_file.perfetto-trace --txt -c scheduling.cfg
 ```
 
 </tabs?>

docs/reference/tracebox.md

@@ -12,8 +12,8 @@ tracebox ctl start
 tracebox -t 10s -o trace.pftrace sched freq
 tracebox ctl stop
 
-# Self-contained mode (legacy)
-tracebox --legacy -t 10s -o trace.pftrace sched
+# Autodaemonize mode (self-contained)
+tracebox --autodaemonize -t 10s -o trace.pftrace sched
 
 # Invoke bundled applets
 tracebox [applet_name] [args ...]
@@ -24,15 +24,9 @@ tracebox [applet_name] [args ...]
 `tracebox` bundles the Perfetto tracing service (`traced`), system probes
 (`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 `--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.
+**Update (2025):** `tracebox` now prefers daemons to be managed explicitly via
+`tracebox ctl` for better SDK compatibility and performance. The classic
+self-contained behavior is still available via the `--autodaemonize` flag.
 
 ## DAEMON MANAGEMENT
 
@@ -74,29 +68,24 @@ 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`
 
-## LEGACY SELF-CONTAINED MODE
+## AUTODAEMONIZE 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 (formerly default behavior) spawns temporary daemons for the
+duration of a single trace session. This mode uses private, temporary sockets
+and is fully self-contained.
 
 **When to use:**
-- For quick one-off traces where you don't want to manage daemons.
+- For quick one-off traces where setup simplicity is prioritized over performance.
 - 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.
+- For existing scripts or workflows that expect self-contained execution.
 
-**Limitations:**
-- **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).
+**Note:** SDK-instrumented apps (using `track_event`) may fail to connect to
+these temporary daemons due to private socket usage. For SDK tracing, the
+`tracebox ctl` workflow is strongly recommended.
 
 **Example:**
 ```bash
-tracebox --legacy -t 10s -o trace.pftrace sched freq
+tracebox --autodaemonize -t 10s -o trace.pftrace sched freq
 ```
 
 ## APPLET MODE
@@ -130,7 +119,7 @@ tracebox ctl status  # Check daemon status
 
 If daemons aren't running:
 - Use `tracebox ctl start` to start them
-- Or use `--legacy` for self-contained mode
+- Or use `--autodaemonize` for self-contained mode
 
 ### Permission denied
 
@@ -158,56 +147,24 @@ sudo systemctl stop traced traced-probes
 tracebox ctl start
 ```
 
-## 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.
+## CHOOSING A WORKFLOW
+
+`tracebox` supports two main workflows. Choose the one that best fits your needs.
+
+### Option A: Persistent Daemons (Recommended)
+Best for: SDK tracing, repeated tracing, system-wide analysis.
+
+1.  Start daemons once: `tracebox ctl start`
+2.  Record traces: `tracebox -t 10s ...`
+3.  Stop (optional): `tracebox ctl stop`
+
+### Option B: Autodaemonize Mode
+Best for: Quick ftrace-only debugging, scripts requiring self-contained binaries.
+
+1.  Record trace: `tracebox --autodaemonize -t 10s ...`
+
+This mode behaves like older `tracebox` versions, spawning temporary daemons
+for the duration of the command.
 
 ## SEE ALSO
 

src/tracebox/tracebox.cc

@@ -60,12 +60,22 @@ void PrintTraceboxUsage() {
   printf(R"(Welcome to Perfetto tracing!
 
 Tracebox is a bundle containing all the tracing services and the perfetto
-cmdline client in one binary.
+cmdline client in one binary. It can be used in two modes:
 
-QUICK START (end-to-end workflow):
-  tracebox ctl start                      # Start daemons
-  tracebox -t 10s -o trace.pftrace sched  # Capture trace
-  tracebox ctl stop                       # Stop daemons (optional)
+MODE 1: Daemon mode (Recommended)
+  Background daemons are started once and shared across multiple tracing sessions.
+  This supports SDKs (track_event), reduces latency and is generally more robust.
+
+  > tracebox ctl start
+  > tracebox -t 10s -o trace.pftrace sched
+  > tracebox ctl stop
+
+MODE 2: Autodaemonize mode
+  Spawns temporary daemons only for the duration of the trace.
+  Useful for quick ftrace debugging or self-contained scripts.
+  Note: SDK apps (track_event) might not connect due to private sockets.
+
+  > tracebox --autodaemonize -t 10s -o trace.pftrace sched
 )");
 
   PrintTraceboxCtlUsage();
@@ -75,13 +85,6 @@ QUICK START (end-to-end workflow):
     applets += " " + std::string(applet.name);
 
   printf(R"(
-ADVANCED: --legacy (NOT RECOMMENDED)
-  Example: tracebox --legacy -t 10s -o trace.pftrace sched
-
-  Spawns temporary daemons for one trace only.
-  Limitations: SDK apps won't connect, inefficient for multiple traces.
-  Use only for quick one-offs or when persistent daemons aren't feasible.
-
 Available applets:%s
 
 See also:
@@ -91,8 +94,9 @@ See also:
          applets.c_str());
 }
 
-// Legacy mode: spawns temporary daemons with private sockets for one trace.
-int RunLegacy(int argc, char** argv) {
+// Autodaemonize mode: spawns temporary daemons with private sockets for one
+// trace.
+int RunAutodaemonize(int argc, char** argv) {
   auto* end = std::remove_if(argv, argv + argc, [](char* arg) {
     return !strcmp(arg, "--system-sockets");
   });
@@ -242,11 +246,11 @@ int TraceboxMain(int argc, char** argv) {
     return 1;
   }
 
-  bool legacy_mode = false;
+  bool autodaemonize = false;
   bool use_system_sockets = false;
   for (int i = 1; i < argc;) {
-    if (strcmp(argv[i], "--legacy") == 0) {
-      legacy_mode = true;
+    if (strcmp(argv[i], "--autodaemonize") == 0) {
+      autodaemonize = true;
       memmove(static_cast<void*>(&argv[i]), static_cast<void*>(&argv[i + 1]),
               sizeof(char*) * static_cast<size_t>(argc - i - 1));
       argc--;
@@ -258,39 +262,41 @@ int TraceboxMain(int argc, char** argv) {
     }
   }
 
-  if (legacy_mode) {
+  if (autodaemonize) {
+    // If --system-sockets is passed with --autodaemonize, it's a valid (though
+    // slightly contradictory in name) way to say "spawn daemons but use public
+    // sockets". We warn if they try to mix them in a way that suggests they
+    // expect the old default behavior without the flag.
     if (use_system_sockets) {
       PERFETTO_ELOG(
-          "Legacy mode using system sockets is deprecated. Please prefer to "
-          "start daemons separately with `tracebox ctl start` for better "
-          "stability and compatibility. See "
-          "https://perfetto.dev/docs/reference/tracebox for details.");
-    } else {
-      PERFETTO_ELOG(
-          "Using legacy autodaemonize mode. This is fine for quick "
-          "one-off traces, but for production use or SDK compatibility, please "
-          "use `tracebox ctl start` followed by `tracebox`. See "
-          "https://perfetto.dev/docs/reference/tracebox for details.");
+          "Warning: --system-sockets with --autodaemonize is supported but "
+          "deprecated. Prefer `tracebox ctl start` for persistent daemons.");
     }
-    return RunLegacy(argc, argv);
+    // We don't warn for plain --autodaemonize as it's a valid mode.
+    return RunAutodaemonize(argc, argv);
   }
 
   if (use_system_sockets) {
     PERFETTO_FATAL(
-        "System sockets is not a valid option for the new mode. By default "
-        "tracebox uses system sockets. If you want the old self-contained "
-        "behavior (autostarting daemons), append --legacy.");
+        "System sockets is the default. If you want the old self-contained "
+        "behavior (spawning temporary daemons), use --autodaemonize.");
   }
 
   ServiceSockets sockets = perfetto::GetRunningSockets();
   if (!sockets.IsValid()) {
-    fprintf(stderr,
-            "Error: Perfetto tracing daemons (traced, traced_probes) are not "
-            "running.\n"
-            "- To run daemons as the current user: `tracebox ctl start`\n"
-            "- For a self-contained run: `tracebox --legacy ...` (Not "
-            "Recommended)\n"
-            "More info at: https://perfetto.dev/docs/reference/tracebox\n");
+    fprintf(
+        stderr,
+        "Error: Perfetto tracing daemons (traced, traced_probes) are not "
+        "running.\n\n"
+        "Tracebox behavior has changed. It no longer spawns temporary daemons "
+        "by default.\n"
+        "You have two options:\n"
+        "1. Start the daemons manually (Recommended):\n"
+        "     tracebox ctl start\n"
+        "     tracebox ...\n\n"
+        "2. Use the --autodaemonize flag for the old behavior:\n"
+        "     tracebox --autodaemonize ...\n"
+        "\nMore info at: https://perfetto.dev/docs/reference/tracebox\n");
     return 1;
   }
   perfetto::SetServiceSocketEnv(sockets);