Introduction to Android Performance and Cgroup v2

Modern Android devices are powerful, yet users frequently encounter performance issues ranging from UI jank to application freezes. While many factors contribute to these problems, resource throttling is a common culprit. Operating systems, including Android, employ sophisticated mechanisms to manage and allocate system resources like CPU time, memory, and I/O bandwidth among numerous running processes. On contemporary Android versions, this critical task is largely handled by Cgroup v2 (Control Group v2), a powerful Linux kernel feature.

Understanding how Cgroup v2 operates and, more importantly, how to interpret its diagnostic logs, provides an invaluable toolkit for advanced users, developers, and system integrators to pinpoint and resolve deep-seated performance bottlenecks that might otherwise remain opaque.

Understanding Cgroup v2 in Android

Control Groups (Cgroups) are a Linux kernel feature that limits, accounts for, and isolates the resource usage (CPU, memory, disk I/O, network, etc.) of a collection of processes. Cgroup v2 is the successor to Cgroup v1, offering a unified, hierarchical design that simplifies management and provides more precise control over resource distribution.

In Android, Cgroup v2 plays a foundational role in ensuring system stability and fair resource allocation. The init process, Android’s first process, sets up the basic Cgroup hierarchy, and subsequent services and applications are placed into specific Cgroups based on their priority and state (e.g., foreground, background, cached). This allows the system to prioritize critical processes and throttle less important ones, preventing a single rogue app from monopolizing resources and degrading overall user experience.

Key Cgroup v2 Concepts

• Unified Hierarchy: Unlike v1, v2 uses a single hierarchy where all controllers (cpu, memory, io, etc.) are available.
• No Internal Subtrees: A process can only be in one Cgroup in the hierarchy.
• Delegation: Subtrees can be delegated to unprivileged users, allowing them to manage resources within their allocated slice.
• Controllers: Specific resource management functionalities (e.g., cpu, memory, io).

Accessing Cgroup v2 Information on Android

Accessing Cgroup v2 details requires root access or an ADB shell with sufficient permissions (e.g., adb shell root if your device is rooted or adb shell with a userdebug/eng build). The Cgroup filesystem is typically mounted at /sys/fs/cgroup.

First, connect your device via ADB:

adb shell

Navigate to the Cgroup v2 root:

cd /sys/fs/cgroup

You’ll see various files and directories. Directories represent Cgroups, and files within them are control files (e.g., cpu.stat, memory.stat). The cgroup.controllers file lists the active controllers on the system.

ls -F /sys/fs/cgroup
cat /sys/fs/cgroup/cgroup.controllers

This will show controllers like cpu memory io pids rdma. Android places apps into various groups, often under a path like /dev/cpuset/ (a Cgroup v1 legacy, but also relevant for v2 integration) or directly within the unified Cgroup v2 hierarchy based on process state (e.g., /sys/fs/cgroup/user.slice/... or /sys/fs/cgroup/system.slice/...).

Diagnosing CPU Throttling

CPU throttling is one of the most common performance issues. Cgroup v2 provides detailed statistics in the cpu.stat file within each Cgroup directory.

Consider a hypothetical application with PID 1234. You’d typically find its Cgroup under a path reflecting its user or system status. For instance, processes related to a specific user might be under /sys/fs/cgroup/user/<UID>/ or /sys/fs/cgroup/system/<service_name>/. Let’s assume you’ve found the relevant Cgroup directory.

# Example: Find the cgroup for a process (e.g., com.example.app)
# This often involves looking at /proc/<PID>/cgroup or searching
# for the process name in cgroup paths. For system processes,
# they might be under a slice like system.slice.

# Let's assume we are inspecting the root cgroup or a specific app's cgroup
cat /sys/fs/cgroup/cpu.stat

The output of cpu.stat typically looks like this:

usage_usec 123456789
user_usec 98765432
system_usec 24680246
nr_periods 10000
nr_throttled 500
throttled_usec 1234567

• usage_usec: Total CPU time consumed by the Cgroup (user + system).
• user_usec: CPU time spent in user mode.
• system_usec: CPU time spent in kernel mode.
• nr_periods: Number of times the Cgroup’s CPU usage has been evaluated against its quota.
• nr_throttled: Number of times the Cgroup’s CPU usage exceeded its quota during a period.
• throttled_usec: Total time (in microseconds) the Cgroup spent throttled.

High values for nr_throttled and especially throttled_usec indicate significant CPU throttling. This means the processes in this Cgroup are attempting to use more CPU than they are allowed, and the kernel is actively limiting their execution. If this is happening to a foreground application, it will directly manifest as lag or unresponsiveness.

Diagnosing Memory Throttling

Memory throttling can lead to application crashes, slowness, or system-wide instability. The memory.stat file provides a wealth of information about memory usage within a Cgroup.

cat /sys/fs/cgroup/memory.stat

Key metrics to watch for include:

• anon: Anonymous memory (heap, stack, data segments).
• file: File-backed memory (page cache).
• inactive_anon, active_anon, inactive_file, active_file: Reflect the activity of memory pages.
• kernel_stack: Memory used by kernel stacks.
• sock: Memory used by network sockets.
• slab: Memory used by kernel slab allocators.
• pgfault, pgmajfault: Number of page faults (minor and major). High pgmajfault can indicate heavy swapping or I/O contention.

More direct indicators of memory pressure and throttling are found in files like memory.max, memory.high, and memory.low, which define the limits and soft limits for memory usage. When a Cgroup hits its memory.high limit, the kernel starts actively reclaiming memory from it. If it hits memory.max, an Out-Of-Memory (OOM) killer might be invoked, often targeting the processes within that Cgroup.

# Check memory limits
cat /sys/fs/cgroup/memory.max
cat /sys/fs/cgroup/memory.high
cat /sys/fs/cgroup/memory.low

# Check OOM events (group-specific)
cat /sys/fs/cgroup/memory.oom.group

A non-zero value in memory.oom.group (or a related OOM event counter) indicates that processes in this Cgroup have triggered the OOM killer. High `pgmajfault` combined with low active memory and high inactive memory can suggest memory pressure causing excessive disk I/O for paging.

Diagnosing I/O Throttling

I/O throttling can cause applications to feel slow, especially when loading data, saving files, or interacting with databases. Cgroup v2’s io.stat file provides metrics on disk I/O operations.

cat /sys/fs/cgroup/io.stat

The output typically lists per-device I/O statistics:

8:0 rbytes=12345 wbytes=67890 rios=100 wios=50 rtime=1000 wtime=5000
259:0 rbytes=9876 wbytes=54321 rios=200 wios=75 rtime=2000 wtime=7000

• 8:0, 259:0: Device major:minor numbers. You can find their mapping in /proc/partitions.
• rbytes: Total bytes read.
• wbytes: Total bytes written.
• rios: Number of read I/O operations.
• wios: Number of write I/O operations.
• rtime: Total time spent reading (in milliseconds).
• wtime: Total time spent writing (in milliseconds).

High rtime or wtime relative to the bytes or operations (i.e., high latency per operation) suggests I/O bottlenecks. If a specific application’s Cgroup shows disproportionately high rtime/wtime, it indicates that application is either performing excessive I/O or is being throttled by the system’s I/O controller (e.g., due to io.max limits).

Practical Steps for Debugging and Mitigation

Once you’ve identified a Cgroup experiencing significant throttling, the next step is to identify the specific processes or services within that group responsible for the resource contention. You can list processes within a Cgroup using cat cgroup.procs or cat cgroup.threads inside the respective Cgroup directory.

cd /sys/fs/cgroup/user/<UID>/app/com.example.app/ # Example path
cat cgroup.procs
cat cgroup.threads

Further debugging tools include:

• top or htop: To see real-time CPU/memory usage of processes.
• dumpsys cpuinfo: Provides a snapshot of CPU usage across all processes since boot or reset.
• perfetto: Android’s system tracing tool, which can capture Cgroup metrics alongside other system events, providing a holistic view of performance over time.

Mitigation strategies might include:

• Application Optimization: If an app is the culprit, optimizing its code to reduce CPU cycles, memory footprint, or I/O operations is key.
• System Configuration: For rooted devices or custom ROMs, one might adjust Cgroup parameters directly (e.g., cpu.max, memory.high) for specific services, though this requires deep system understanding and carries risks.
• Process Management: Ensuring background apps are properly suspended or killed.

Conclusion

Cgroup v2 logs offer an unparalleled window into the kernel’s resource management decisions on Android. By systematically examining cpu.stat, memory.stat, and io.stat within relevant Cgroups, technical users and developers can move beyond superficial observations of slowness and diagnose the root causes of resource throttling. This expert-level approach transforms performance troubleshooting from guesswork into a data-driven investigation, paving the way for targeted and effective solutions to improve Android device responsiveness and stability.