TRACED_PROBES(8)

🎀 NAME 🎀

okay so bestie, this is the manual page for traced_probes — System & OS Probes. It lives in section 8 of the System Manager's Manual, and yes, it's giving main character energy for kernel tracing. ✨

---

💖 DESCRIPTION 💖

traced_probes is a specialized daemon that acts as a privileged Producer in the Perfetto architecture. While any application can act as a producer to contribute its own trace data, traced_probes is specifically responsible for collecting system-level and kernel-level data that typically requires elevated privileges. No cap, that's the whole vibe.

🫶 Relationship with traced 🫶

traced_probes is a client of the traced service. It connects to traced’s producer socket and registers a set of data sources. traced then sends requests to traced_probes to start or stop these data sources as part of a tracing session.

This separation of concerns is a key part of Perfetto’s design. traced is the central manager, while traced_probes is a specialized data provider. This decoupled architecture allows for multiple, independent producers and consumers to interact with the tracing system simultaneously without interfering with each other. periodt.

🔐 Security and Privileges 🔐

traced_probes often needs to run with elevated privileges (e.g., root or system user on Android) to access kernel interfaces like debugfs or /proc. Separating these high-privilege probes into their own daemon is a key part of Perfetto’s security model. It ensures that only a minimal amount of code runs with high privileges, adhering to the principle of least privilege. 💅

⚙️ Configuration ⚙️

The data sources provided by traced_probes are configured within the main trace configuration protobuf that is sent to traced. For example, to enable ftrace, you would include an FtraceConfig within the DataSourceConfig for the linux.ftrace data source. iykyk.

🌈 Data Sources 🌈

traced_probes provides a wide range of data sources, collecting system-level and kernel-level data. The configuration for these data sources is specified in the data_sources section of the overall trace configuration. Each data source has its own configuration message within a data_source_config block.

Here is an example of the general structure:

data_sources: {
    config {
        name: "linux.ftrace"
        ftrace_config {
            # ... ftrace-specific settings
        }
    }
}
data_sources: {
    config {
        name: "linux.process_stats"
        process_stats_config {
            # ... process_stats-specific settings
        }
    }
}

Below is a detailed list of the main data sources provided by traced_probes, separated by platform.

🐧 Linux Data Sources 🐧

These data sources are available on Linux-based systems, including Android. Android besties, this one's for you too.

Here is an example of a trace config enabling several Linux data sources:

# Example of a trace config enabling several Linux data sources.
data_sources: {
    config {
        name: "linux.ftrace"
        ftrace_config {
          ftrace_events: "sched/sched_switch"
          ftrace_events: "power/cpu_idle"
        }
    }
}
data_sources: {
    config {
        name: "linux.process_stats"
        process_stats_config {
          scan_all_processes_on_start: true
          proc_stats_poll_ms: 1000
        }
    }
}
data_sources: {
    config {
        name: "linux.sys_stats"
        sys_stats_config {
          meminfo_period_ms: 1000
          vmstat_period_ms: 1000
        }
    }
}

🔥 linux.ftrace (Kernel Tracing) 🔥

• Description: This is the primary data source for high-frequency kernel events. It enables and reads raw ftrace data from the Linux kernel’s ftrace interface, providing insights into process scheduling, system calls, interrupts, and other kernel activities. the way that it eats, no crumbs.
• Configuration Example:

data_sources: {
  config {
    name: "linux.ftrace"
    ftrace_config {
      ftrace_events: "sched/sched_switch"
      ftrace_events: "power/cpu_idle"
      ftrace_events: "sched/sched_waking"
    }
  }
}

• Configuration: Configured via FtraceConfig within the DataSourceConfig. Key options include:
  • ftrace_events — List of ftrace events to enable (e.g., sched/sched_switch).
  • atrace_categories, atrace_apps — For Android, enables userspace Atrace categories and apps.
  • syscall_events — Specific syscalls to trace.
  • enable_function_graph — Enables kernel function graph tracing.
  • compact_sched — Enables compact encoding for scheduler events.
  • symbolize_ksyms — Enables kernel symbolization.
  • print_filter — Filters ftrace/print events based on content.

🍓 linux.process_stats (Process and Thread Statistics) 🍓

• Description: Collects detailed process and thread-level statistics from the /proc filesystem. It provides both a snapshot of the process tree and periodic memory/CPU counters. fr fr, it's watching the whole process tree.
• Configuration Example:

data_sources: {
  config {
    name: "linux.process_stats"
    process_stats_config {
      scan_all_processes_on_start: true
      proc_stats_poll_ms: 1000
    }
  }
}

• Configuration: Configured via ProcessStatsConfig. Key options include:
  • record_thread_names — Record thread names.
  • scan_all_processes_on_start — Dump the entire process tree at the start.
  • resolve_process_fds — Resolve file descriptor paths.
  • scan_smaps_rollup — Read /proc/[pid]/smaps_rollup.
  • record_process_age — Record process start time.
  • record_process_runtime — Record user and kernel mode CPU times.
  • record_process_dmabuf_rss — Record DMA buffer RSS.
  • proc_stats_poll_ms — Polling interval for periodic stats.
  • proc_stats_cache_ttl_ms — Time-to-live for cached stats.
  • quirks — Special behaviors (e.g., DISABLE_ON_DEMAND).

🦋 linux.sys_stats (System-Wide Statistics) 🦋

• Description: Collects system-wide statistics by periodically polling various files in /proc and /sys. system-wide? she's everywhere.
• Configuration Example:

data_sources: {
  config {
    name: "linux.sys_stats"
    sys_stats_config {
      meminfo_period_ms: 1000
      vmstat_period_ms: 1000
      stat_period_ms: 1000
    }
  }
}

• Configuration: Configured via SysStatsConfig. Allows fine-grained control over which counters to collect and their polling frequencies (e.g., meminfo_period_ms, vmstat_period_ms, stat_counters).

💜 linux.sysfs_power (Power and Battery Information) 💜

• Description: Collects power and battery statistics using the Linux sysfs interface. lowkey important for battery girlies.
• Configuration Example:

data_sources: {
  config {
    name: "linux.sysfs_power"
  }
}

• Configuration: This data source does not have a specific configuration proto.

🧚 linux.inode_file_map (Inode to File Path Mapping) 🧚

• Description: Maps inode numbers to file paths, which is useful for correlating I/O events with the files being accessed. matching the vibe of every file, iconic.
• Configuration Example:

data_sources: {
  config {
    name: "linux.inode_file_map"
    inode_file_config {
      scan_interval_ms: 10000
      scan_delay_ms: 5000
      scan_batch_size: 1000
    }
  }
}

• Configuration: InodeFileConfig allows specifying scan_mount_points, mount_point_mapping (to remap scan roots), scan_interval_ms, scan_delay_ms, scan_batch_size, and do_not_scan.

🌸 metatrace (Perfetto Self-Tracing) 🌸

• Description: A self-tracing data source that records events within Perfetto itself, useful for debugging and performance analysis of the tracing system. not me being self-aware, but go off.
• Configuration Example:

data_sources: {
  config {
    name: "metatrace"
  }
}

• Configuration: No specific configuration in DataSourceConfig.

🌟 linux.system_info (System Information) 🌟

• Description: Records general information about the system, such as CPU details and kernel version. the basics, but make it cute.
• Configuration Example:

data_sources: {
  config {
    name: "linux.system_info"
  }
}

• Configuration: No specific configuration in DataSourceConfig.

🌈 ANDROID DATA SOURCES 🌈

Okay bestie, listen — these ones are Android only. Like, no Android device, no data source, periodt. So if you're on some other platform, this whole section is just ✨ lore ✨ to you.

Here's an example trace config that turns on a bunch of Android data sources at once, and yes you can absolutely steal it:

# Example of a trace config enabling several Android data sources.
data_sources: {
    config {
        name: "android.power"
        android_power_config {
          battery_poll_ms: 1000
          battery_counters: BATTERY_COUNTER_CHARGE
          collect_power_rails: true
        }
    }
}
data_sources: {
    config {
        name: "android.log"
        android_log_config {
          log_ids: LID_DEFAULT
          log_ids: LID_SYSTEM
        }
    }
}
data_sources: {
    config {
        name: "android.packages_list"
    }
}

---

🍓 android.power (Power and Battery Information)

• Description: It collects power and battery statistics using Android-specific HALs. Very demure, very battery-aware.
• Configuration Example:

data_sources: {
  config {
    name: "android.power"
    android_power_config {
      battery_poll_ms: 1000
      battery_counters: BATTERY_COUNTER_CHARGE
      battery_counters: BATTERY_COUNTER_CAPACITY_PERCENT
      collect_power_rails: true
    }
  }
}

• Configuration: AndroidPowerConfig lets you turn on specific battery counters (battery_counters), power rails (collect_power_rails), the energy estimation breakdown (collect_energy_estimation_breakdown), and entity state residency (collect_entity_state_residency). Choose your fighter 💅

---

🌸 android.log (Android Logcat)

• Description: It streams log messages straight from Android's logcat buffer into your trace. Basically catching logcat in 4k 🔥
• Configuration Example:

data_sources: {
  config {
    name: "android.log"
    android_log_config {
      log_ids: LID_DEFAULT
      log_ids: LID_SYSTEM
      min_prio: PRIO_INFO
      filter_tags: "ActivityManager"
    }
  }
}

• Configuration: AndroidLogConfig lets you filter by log IDs (log_ids) and tags (filter_tags), and you can set a minimum priority with (min_prio). Filtering is self care, no cap.

---

🦋 android.system_property (Android System Properties)

• Description: It collects the state of Android system properties. The little behind-the-scenes settings? Yeah, those.
• Configuration Example:

data_sources: {
  config {
    name: "android.system_property"
    android_system_property_config {
      poll_ms: 1000
      property_name: "debug.tracing.screen_state"
    }
  }
}

• Configuration: AndroidSystemPropertyConfig lets you name the property_names you wanna monitor and set a poll_ms interval. Iconic.

---

🎀 android.packages_list (Android Package Information)

• Description: It dumps info about the installed packages on Android. A whole little census of your apps 🫶
• Configuration Example:

data_sources: {
  config {
    name: "android.packages_list"
    packages_list_config {
      package_name_filter: "com.android.systemui"
      package_name_filter: "com.google.android.apps.nexuslauncher"
    }
  }
}

• Configuration: PackagesListConfig lets you filter by package_name_filter, and it can be configured to either only_write_on_cpu_use_every_ms (that's the polling mode bestie) or just dump everything at the start.

---

🧚 android.game_interventions (Android Game Intervention List)

• Description: It dumps the game intervention list from the package manager on Android. Gaming mode lore unlocked.
• Configuration Example:

data_sources: {
  config {
    name: "android.game_interventions"
    android_game_intervention_list_config {
      package_name_filter: "com.example.mygame"
    }
  }
}

• Configuration: AndroidGameInterventionListConfig lets you filter by package_name_filter. Simple, clean, slay.

---

💜 android.cpu.uid (Per-UID CPU Time)

• Description: It collects per-UID CPU time from the kernel. Yes, we're going straight to the kernel for this one.
• Configuration Example:

data_sources: {
  config {
    name: "android.cpu.uid"
    cpu_per_uid_config {
      poll_ms: 1000
    }
  }
}

• Configuration: CpuPerUidConfig lets you set the poll_ms interval. That's it, that's the whole thing ✨

---

🔥 android.kernel_wakelocks (Kernel Wakelocks)

• Description: It collects kernel wakelock information. Who's keeping your device awake at 3am? This knows.
• Configuration Example:

data_sources: {
  config {
    name: "android.kernel_wakelocks"
    kernel_wakelocks_config {
      poll_ms: 1000
    }
  }
}

• Configuration: KernelWakelocksConfig lets you set the poll_ms interval. Periodt.

---

🌼 android.polled_state (Android Initial Display State)

• Description: It records the initial display state on Android — think screen on/off, brightness, that whole vibe.
• Configuration Example:

data_sources: {
  config {
    name: "android.polled_state"
    android_polled_state_config {
      poll_ms: 500
    }
  }
}

• Configuration: AndroidPolledStateConfig lets you set a poll_ms interval. Short and sweet.

---

⭐ android.statsd (Android StatsD Atoms)

• Description: It collects StatsD atoms from the binder interface on Android. Atoms!! So very science of it.
• Configuration Example:

data_sources: {
  config {
    name: "android.statsd"
    statsd_tracing_config {
      pull_config {
        pull_atom_id: 10000 # Example pull atom
        pull_frequency_ms: 1000
      }
      push_atom_id: 10037 # Example push atom
    }
  }
}

• Configuration: StatsdTracingConfig lets you specify pull_config (for pull atoms, with their frequency and packages) and push_atom_id (for push atoms). Pull vs push, the eternal duo 🦋

---

okay that's the whole Android lineup bestie, every single one accounted for, nothing skipped, nothing merged 💖

And that's a wrap on the page! The footer down there was repping TRACED_PROBES(8) — section 8, tracing-and-probes business, dated whenever this page got refreshed. Anyway mwah, go trace something, you've got this 👑💅