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,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`
 
-## 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`
+- **Concurrency:** Running multiple instances of `tracebox --autodaemonize`
   concurrently can lead to resource conflicts (e.g. with ftrace).
 
 **Example:**
 ```bash
-tracebox --legacy -t 10s -o trace.pftrace sched freq
+tracebox --autodaemonize -t 10s -o trace.pftrace sched freq
 ```
 
 ## APPLET MODE
@@ -130,7 +124,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
 
@@ -171,43 +165,22 @@ 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.
+`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);

src/tracebox/tracebox_ctl.cc

@@ -45,6 +45,10 @@
 namespace perfetto {
 namespace {
 
+// Environment variables for socket paths.
+constexpr char kPerfettoProducerSockEnv[] = "PERFETTO_PRODUCER_SOCK_NAME";
+constexpr char kPerfettoConsumerSockEnv[] = "PERFETTO_CONSUMER_SOCK_NAME";
+
 constexpr const char* kDaemons[] = {
     "traced",
     "traced_probes",
@@ -145,7 +149,7 @@ int CtlStop() {
       "to stop them.\n");
   return 1;
 #else
-  printf("Stopping daemons...\n");
+  PERFETTO_LOG("Stopping daemons...");
   bool found_any = false;
   bool all_stopped = true;
   for (const char* daemon : kDaemons) {
@@ -163,7 +167,7 @@ int CtlStop() {
     }
   }
   if (!found_any) {
-    printf("No daemon PID files found.\n");
+    PERFETTO_LOG("No daemon PID files found.");
     ServiceSockets sockets = GetRunningSockets();
     if (!sockets.IsValid()) {
       printf("No daemons detected.\n");
@@ -180,7 +184,7 @@ int CtlStop() {
             "traced-probes\n");
         return 0;
       }
-      printf("Systemd service found. Trying to stop via systemctl...\n");
+      PERFETTO_LOG("Systemd service found. Trying to stop via systemctl...");
       if (system("systemctl stop traced traced-probes") == 0) {
         printf("Daemons stopped.\n");
         return 0;
@@ -209,7 +213,7 @@ int CtlStart() {
   }
 
 #if PERFETTO_BUILDFLAG(PERFETTO_OS_WIN)
-  printf("Starting daemons...\n");
+  PERFETTO_LOG("Starting daemons...");
   std::string tracebox_path = base::GetCurExecutablePath();
   std::vector<base::Subprocess> processes;
   for (const char* daemon : kDaemons) {
@@ -240,7 +244,7 @@ int CtlStart() {
 #else  // Unix
   if (IsSystemdServiceInstalled()) {
     if (base::GetCurrentUserId() == 0) {
-      printf("Starting daemons via systemd...\n");
+      PERFETTO_LOG("Starting daemons via systemd...");
       if (system("systemctl start traced traced-probes") == 0) {
         ServiceSockets sys_sockets = GetRunningSockets();
         SetServiceSocketEnv(sys_sockets);
@@ -254,7 +258,7 @@ int CtlStart() {
         "systemctl start traced traced-probes");
     return 1;
   }
-  printf("Starting daemons...\n");
+  PERFETTO_LOG("Starting daemons...");
   std::string tracebox_path = base::GetCurExecutablePath();
   for (const char* daemon : kDaemons) {
     pid_t pid = StartDaemon(tracebox_path, daemon);
@@ -297,9 +301,9 @@ int CtlStatus() {
     pid_t pid = ReadPidFromFile(pid_path);
     if (pid > 0) {
       if (kill(pid, 0) == 0) {
-        printf("  %-15s : Running (PID %d)\n", daemon, static_cast<int>(pid));
+        printf("  %s : Running (PID %d)\n", daemon, static_cast<int>(pid));
       } else {
-        printf("  %-15s : Not running (Stale PID file %d)\n", daemon,
+        printf("  %s : Not running (Stale PID file %d)\n", daemon,
                static_cast<int>(pid));
         stale_found = true;
       }