tracebox: Explicit daemon management

BUILD.gn

@@ -198,6 +198,9 @@ if (perfetto_build_standalone) {
     # Checks that the "fake" backend implementations build.
     "src/tracing:client_api_no_backends_compile_test",
   ]
+
+  # TODO: Fix build for Windows
+  # https://github.com/google/perfetto/issues/3772
   if (is_linux || is_android || is_mac) {
     all_targets += [ "src/tracebox" ]
   }

CHANGELOG

@@ -19,6 +19,12 @@ Unreleased:
       measurement of slice durations. Hold Alt to temporarily disable snapping.
   SDK:
     *
+  Tools:
+    * 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 `--autodaemonize` 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 # This will start persistent background tracing services
 ./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 # This will start persistent background tracing services
 ./tracebox -c ticker.cfg --txt -o ticker.pftrace
 ```
 
+Alternatively using autodaemonize mode:
+```bash
+./tracebox --autodaemonize -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,22 @@ chmod +x tracebox heap_profile
 
 Start the tracing service
 ```bash
-./tracebox traced &
+./tracebox ctl start # This will start persistent background tracing services
 ```
 
 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 autodaemonize mode (no `ctl start` required):
+
+```bash
+./heap_profile -n trace_processor_shell --print-config | \
+  ./tracebox --autodaemonize -c - --txt -o ~/trace_processor_memory.pftrace
 ```
 
 Open another terminal (or tab), start the process you want to profile,
@@ -213,10 +220,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 # This will start persistent background tracing services
+```
+
+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. `./tracebox ctl start`).
+
+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 --autodaemonize -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

@@ -6,95 +6,102 @@ tracebox - all-in-one binary for Perfetto tracing services
 
 ## DESCRIPTION
 
-`tracebox` is a bundle containing all the tracing services (`traced`,
-`traced_probes`) and the `perfetto` commandline client in one binary.
+`tracebox` bundles all Perfetto tracing services (`traced`, `traced_probes`,
+`traced_perf`) and the `perfetto` command-line client into a single binary. It
+is the primary tool for recording traces on Linux systems where Perfetto is not
+pre-installed as a system service.
 
-It can be used either to spawn manually the various subprocess or in "autostart"
-mode, which will take care of starting and tearing down the services for you.
+**Key behavior change (2025):** `tracebox` no longer spawns temporary daemons by default.
+It expects daemons to be already running. Use `tracebox ctl` to manage them or
+`--autodaemonize` for the classic self-contained mode.
 
-## AUTOSTART MODE
+## MODES OF OPERATION
 
-If no applet name is specified, `tracebox` will behave like the `perfetto`
-command, but will also start `traced` and `traced_probes`.
+`tracebox` supports three distinct modes of operation depending on how you want
+to manage the lifecycle of the tracing services.
 
-See [perfetto(1)](perfetto-cli.md) for the documentation of the commandline client.
+### 1. Managed Mode (Recommended)
 
-### Autostart Mode Usage
+In this mode, you explicitly start and stop the tracing services using the `ctl`
+applet. This creates persistent background daemons that remain active across
+multiple tracing sessions.
 
-The autostart mode supports both simple and normal modes of `perfetto`'s
-operation, and additionally provides a `--system-sockets` flag.
+**Commands:**
 
-The general syntax for using `tracebox` in *autostart mode* is as follows:
+`tracebox ctl start`
+:   Starts `traced` and `traced_probes` in the background.
 
-```
- tracebox [PERFETTO_OPTIONS] [TRACEBOX_OPTIONS] [EVENT_SPECIFIERS]
-```
-
-`--system-sockets`
-:    Forces the use of system-sockets when using autostart mode.
-     By default, `tracebox` uses a private socket namespace to avoid
-     conflicts with system-wide `traced` daemons. This flag forces it to
-     use the standard system sockets, which is useful for debugging
-     interactions with the system `traced` service.
+`tracebox ctl stop`
+:   Stops daemons started via `ctl start`.
 
-#### Simple Mode Example
+`tracebox ctl status`
+:   Checks if daemons are running, accessible, and which sockets they are using.
 
-To capture a 10-second trace of `sched/sched_switch` events in autostart mode:
+**Example Workflow:**
 
 ```bash
-tracebox -t 10s -o trace_file.perfetto-trace sched/sched_switch
+# Start services once (as root for full system/SDK support)
+./tracebox ctl start
+
+# Record multiple traces
+./tracebox -t 10s -o trace1.pftrace sched
+./tracebox -t 10s -o trace2.pftrace sched
+
+# Stop services when finished
+./tracebox ctl stop
 ```
 
-#### Normal Mode Example
+### 2. Autodaemonize Mode
 
-To capture a trace using a custom configuration file in autostart mode:
+In this mode, `tracebox` spawns temporary, ephemeral daemons solely for the
+duration of a single command. The daemons are cleaned up automatically when the
+command finishes.
+
+**Usage:**
+
+Pass the `--autodaemonize` flag before other arguments.
 
 ```bash
-cat <<EOF > config.pbtx
-duration_ms: 5000
-buffers {
-  size_kb: 1024
-  fill_policy: RING_BUFFER
-}
-data_sources {
-  config {
-    name: "linux.ftrace"
-    ftrace_config {
-      ftrace_events: "sched/sched_switch"
-    }
-  }
-}
-EOF
-
-tracebox -c config.pbtx --txt -o custom_trace.perfetto-trace
+# Start daemons, record trace, stop daemons
+./tracebox --autodaemonize -t 10s -o trace.pftrace sched
 ```
 
-## MANUAL MODE
+### 3. Applet Mode
 
-`tracebox` can be used to invoke the bundled applets.
+`tracebox` can behave like any of the bundled binaries if invoked with that
+binary's name as the first argument (or if symlinked to that name).
 
-The general syntax for using `tracebox` in *manual mode* is as follows:
+**Available Applets:** `traced`, `traced_probes`, `traced_perf`, `perfetto`,
+`trigger_perfetto`, `websocket_bridge`, `ctl`.
 
-```
- tracebox [applet_name] [args ...]
+**Example:**
+
+```bash
+# equivalent to running the standalone 'perfetto' client
+./tracebox perfetto -t 10s -o trace.pftrace sched
 ```
 
-The following applets are available:
+## CHOOSING BETWEEN MANAGED AND AUTODAEMONIZE
 
-`traced`
-:    The Perfetto tracing service daemon.
+Choosing the right mode depends on your specific tracing needs, particularly
+regarding application instrumentation and workflow frequency.
 
-`traced_probes`
-:    Probes for system-wide tracing (ftrace, /proc pollers).
+### When to use Managed Mode (`ctl`)
 
-`traced_perf`
-:    Perf-based CPU profiling data source.
+This is the preferred mode for most workflows.
 
-`perfetto`
-:    The commandline client for controlling tracing sessions.
+*   **SDK/App Tracing:** If you are tracing applications instrumented with the
+    Perfetto SDK (using `track_event`), you **must** use Managed Mode (usually
+    as root). SDK applications connect to the standard system socket paths
+    (e.g., `/run/perfetto/` on Linux).
+*   **Repeated Tracing:** If you are recording multiple traces in succession,
+    Managed Mode avoids the overhead of restarting the services for every trace.
+*   **Interactivity:** Useful when manually exploring system behavior and you
+    want the tracing service to be always available.
 
-`trigger_perfetto`
-:    A utility to activate triggers for a tracing session.
+### When to use Autodaemonize Mode
 
-`websocket_bridge`
-:    A bridge for connecting to the tracing service via websockets.
+*   **One-off Scripts:** Useful for self-contained scripts or cron jobs where
+    you want to ensure no leftover processes remain after execution.
+*   **Debugging:** Quick verification of ftrace events where setting up a full
+    service is unnecessary.

src/tracebox/BUILD.gn

@@ -31,5 +31,9 @@ executable("tracebox") {
   if (enable_perfetto_traced_perf) {
     deps += [ "../profiling/perf:traced_perf_main" ]
   }
-  sources = [ "tracebox.cc" ]
+  sources = [
+    "tracebox.cc",
+    "tracebox_ctl.cc",
+    "tracebox_ctl.h",
+  ]
 }