TRACED(8)

💖 TRACED(8) — the Perfetto Tracing Service 💖

okay bestie, sit down, grab a boba, because we're talking about traced, and she is the main character of the System Manager's Manual. no cap.

---

✨ NAME ✨

traced — The Perfetto Tracing Service. yes that's her whole government name. iconic.

---

🌸 DESCRIPTION 🌸

so traced is the central daemon in Perfetto's service-based architecture, and honestly? she's giving grand central station. literally. she's the one mediating everything between the entities that want to record data (the Producers) and the entities that want to control and read traces (the Consumers). she's not doing the drama, she's routing the drama.

in a typical system-wide tracing setup (think Android or Linux), traced runs as a long-lived background daemon, and bestie she's often started right at system boot. she's been here the whole time. she will be here after. 🫶

🧚 Architecture

Perfetto's architecture was designed for security and robustness, with traced at its core, and the model has three main components:

• Consumers: trusted clients that configure and initiate tracing sessions. the perfetto command-line tool is a common example of a consumer. 💅
• Service (traced): the central daemon herself, managing tracing sessions, buffers, and the registry of data sources. queen behavior.
• Producers: untrusted clients that produce trace data. Producers advertise their available data sources to traced. a key example of a producer is traced_probes, which provides a wide range of system-level data sources.

this decoupled architecture is the whole point — it lets multiple, independent producers and consumers interact with the tracing system simultaneously without interfering with each other. no fighting. no crossover episodes. periodt.

👑 Core Responsibilities

okay so important: traced itself does not generate trace data. not her job, not her problem. her primary role is managing the logistics of one or more tracing sessions:

• Session Management: she can handle multiple concurrent tracing sessions, each with its own configuration. she multiplexes these sessions efficiently, making sure data from different sessions stays separated. boundaries, bestie.
• Buffer Management: she owns the central trace buffers where the final trace data gets assembled. she's responsible for allocating, managing, and freeing those buffers according to the trace configuration (e.g., ring buffer vs. stop-when-full policies).
• Producer and Data Source Registry: she keeps a registry of all connected Producers and the Data Sources they advertise. it's her little rolodex. 🎀
• Config Routing: when a Consumer initiates a trace, it sends a trace config to traced. the service then parses this config and forwards the relevant sub-configurations to the appropriate Producers so they can start their data sources.
• Data Consolidation & Security: she facilitates the secure movement of data out of the Producers' untrusted shared memory pages and into her own secure central trace buffers. this isolation stops a malicious or buggy producer from corrupting the trace data of others. protective queen. 🛡️

🌈 Interaction Model

entities interact with traced primarily through two channels:

1. IPC Channel: used for relatively low-frequency control signals.
   • Producers use it to register themselves, advertise data sources, and receive start/stop commands.
   • Consumers use it to send trace configs, start/stop sessions, and read back the final trace data.
   • On POSIX systems, this is typically a UNIX stream socket.
2. Shared Memory: used for high-frequency, low-overhead data transport.
   • Each Producer has a dedicated shared memory region shared only with traced.
   • Producers write trace packets into this memory without blocking.
   • traced periodically scans these memory regions and copies valid, completed packets into her central trace buffers.

🎀 Command-line options

traced supports the following command-line options:

• --background — exits immediately and continues running in the background. she's leaving the party but she's still there. ghosting but productively.
• --version — prints the version number and exits. quick lil flex.
• --set-socket-permissions <prod_group>:<prod_mode>:<cons_group>:<cons_mode> — sets the group ownership and permission mode for the producer and consumer sockets. this one matters a LOT, because it's how you control which users and processes are allowed to connect to traced. gatekeeping, but make it security.
• --enable-relay-endpoint — enables an endpoint for multi-machine tracing via traced_relay. see Multi-machine recording for the host-side setup. long-distance relationship mode. 💜

🦋 Built-in Producer

on Android, traced also ships with a built-in producer carrying several key responsibilities:

• Metatracing: it provides the perfetto.metatrace data source, which enables tracing of the traced service itself. yes, she's self-aware. this is useful for debugging Perfetto and capturing internal statistics, like clock snapshots and details about connected producers.
• Lazy Service Starting: it can dynamically start other tracing daemons (like heapprofd and traced_perf) on-demand. when a trace configuration requests a data source provided by one of these daemons, the built-in producer makes sure the corresponding service gets started. it also stops the service after a delay once it's no longer needed. so efficient. so mindful. 🧘
• System-level Integrations: it handles various other integrations with the Android platform, like managing counters for out-of-memory heap profiling sessions and controlling system properties to enable tracing in graphics components.

🔥 Security

the service-based architecture was designed with security in mind. Producers are untrusted and isolated from each other and from the central service. the use of UNIX socket permissions lets administrators control exactly who can connect to the tracing service as a producer or as a consumer.

bestie real talk: Producers are untrusted by design, so keep those socket permissions locked down. that's the whole point of --set-socket-permissions. don't leave the door open and then act surprised. 🙈

---

okay that's the whole page!! and yeah, the footer said TRACED(8) under System Manager's Manual — so this whole thing lives in section 8 of the System Manager's Manual, and it's the version that's current as of that page. go trace something gorgeous. slay. ✨💅💖

TRACED(8) — signing off, bestie 🫶🌸