cphlipot1

This commit **introduces a new feature** to the **Perfetto UI's Power Rails plugin**, enabling the grouping of power rails by their associated subsystem. It leverages existing subsystem metadata, previously unexposed in the UI, to create logical track groups. This enhancement significantly **improves the organization and readability** of power rail traces, making it easier for users to identify and analyze power consumption within specific subsystems. The update to `ui/src/plugins/dev.perfetto.PowerRails/index.ts` primarily affects the `onActivate` function, enhancing the visualization of power rail data.

This commit introduces a **new capability** to the **Perfetto tracing system** by adding a `preserve_log_buffer` option to the `AndroidLogConfig`. This **enhancement** allows users to capture logcat buffers that existed *before* a trace started, providing crucial historical context for debugging early system behaviors like boot sequences. The `android.log` data source now respects this configuration, modifying the underlying `logcat` command to include `tail=1` when enabled. This significantly improves the diagnostic power for transient or pre-trace events within the **Android logging subsystem**, mirroring the existing `preserve_ftrace` functionality.

This commit **refactors** the **Perfetto SQL standard library** by updating the data type of the `machine_id` column and parameter from `LONG` to `JOINID(machine.id)` across numerous SQL definitions. This **type correction** aligns with new conventions where `machine_id` is no longer null for the primary machine, enabling **trivial joining** and improving data consistency. The change impacts various **Android and Linux-specific SQL definitions**, including tables like `android_device_name` and `linux_kernel_threads`, several `prelude` views and track definitions, and the `_is_linux_machine` function. This **maintenance** effort enhances the overall usability and correctness of the `stdlib`'s multi-machine tracing capabilities.

This commit introduces a **new capability** to the **UI's flamegraph visualization**, enabling users to weight flamegraphs by performance event counts, which is now the default behavior. It enhances the **LinuxPerf plugin** by modifying flamegraph generation to support various perf event metrics, and adds a new SQL macro `_callstacks_for_callsites_weighted` in the **Trace Processor** for backend data processing. This **enhancement** provides a more accurate and insightful representation of performance bottlenecks, significantly improving the utility of flamegraphs for performance analysis.

This commit **enhances** the **Perfetto SQL standard library** by introducing a `machine_id` column to the `android_suspend_state` table. This **new capability** allows for the differentiation of suspend states originating from various Android devices within a single trace, significantly improving the accuracy of multi-device analysis. The updated logic in `src/trace_processor/perfetto_sql/stdlib/android/suspend.sql` now correctly processes and distinguishes suspend events across different machines. New test cases were added to `test/trace_processor/diff_tests/stdlib/android/tests.py` to validate this multi-machine functionality and ensure robustness in scenarios with no suspend events.

This commit introduces a **new capability** to the **Trace Processor** by implementing RFC-0015, allowing the **correlation of perf sample callstacks with associated counter values**. It modifies the **perf importer** and **profiling module** to link `perf_sample` entries to new `PerfCounterSetTable` entries during trace parsing. A new SQL intrinsic `__intrinsic_perf_counter_for_sample` and a `linux_perf_sample_with_counters` view are added to the **stdlib**, providing users with powerful tools to analyze performance data and enable more insightful, counter-weighted flamegraphs.

This commit provides a **maintenance bug fix** to resolve compilation errors encountered when building with the **latest Apple Clang (version 17.0.0)**. Specifically, it addresses issues where the `_Nonnull` type nullability specifier in the **Abseil C++ library** was causing `-Werror,-Wnullability-extension` failures. The fix involves modifying `buildtools/BUILD.gn` to add a compiler flag that disables this particular warning for Abseil C++ sources. This ensures successful compilation and continued compatibility for developers using **macOS with updated Clang versions**.

This commit **fixes a documentation organizational error** by relocating external resources related to `perf script`. Previously, these resources were incorrectly listed under a **Mac Instruments section** in `docs/getting-started/other-formats.md`. The change moves them to their proper place within the dedicated **`perf script` section**, which was previously missing such references. This **documentation maintenance** improves the clarity and accuracy of the getting started guide, ensuring users can easily find relevant external materials for `perf script`.

This commit provides a **documentation fix** for the **Atrace guide**, specifically addressing errors within the `docs/getting-started/atrace.md` file. It corrects numerous typos, grammatical mistakes, and missing words to significantly improve the readability and accuracy of the guide. Furthermore, it rectifies incorrect API usage in code examples, such as C++ syntax appearing in Java examples and changing `dev->buffer` to `dev.buffer`, and updates a broken URL link. This **maintenance** work ensures the Atrace documentation is precise and helpful for developers learning to use the tracing tool.

This commit introduces a **new capability** to the **`trace_processor` `stdlib`** by enhancing the `android_device_name` table to support **multi-machine traces**. It adds a `machine_id` column to `android_device_name` and updates the underlying query in `src/trace_processor/perfetto_sql/stdlib/android/device.sql` to extract device names from the `machine` table. This **data source migration** from the `metadata` table ensures accurate device identification when multiple machines are present in a trace. This **feature** allows users to correctly determine the device name for each machine, significantly improving the utility of **multi-machine trace analysis**. A new test case, `test_android_device_name_multi_machine`, has been added to verify this functionality.

This commit **fixes** a **bug** in the **trace processor's proto importer** by correcting the default timestamp clock ID. Previously, if no clock ID was specified in a trace packet, it would incorrectly default to zero; now, it correctly defaults to `BUILTIN_CLOCK_BOOTTIME` as per the protocol's specification. This ensures **accurate timestamp interpretation** for imported trace data, impacting **trace parsing and UI visualization**. The change is validated by updates to parsing tests and UI screenshot baselines, reflecting the corrected behavior.

This commit **fixes** a **bug** in the **Android probes module** of `trace_processor` where `timestamp_ms` in **power rail energy data** was incorrectly interpreted as trace time instead of `CLOCK_BOOTTIME` as specified by the protobuf. The logic in `src/trace_processor/importers/proto/android_probes_module.cc` is updated to correctly convert these timestamps to the trace time domain if `timestamp_ms` is set. This ensures accurate clock synchronization for energy data, preventing potential failures when the primary trace clock differs from `CLOCK_BOOTTIME`. A **diff test** in `test/trace_processor/diff_tests/parser/power/tests_power_rails.py` was also updated to verify this conversion and cover both clock synchronization paths.

This commit introduces a **new test** to validate the functionality of **power rail traces** within a **multi-device tracing context**. It adds the `test_power_rails_multi_device` method to `test/trace_processor/diff_tests/parser/power/tests_power_rails.py`, specifically targeting the **trace processor's power parsing** capabilities. This **testing** effort ensures the accurate processing and interpretation of power data from multiple machines, thereby enhancing the reliability and **quality assurance** of **power analysis** for complex multi-SoC systems.

This commit **improves the user experience** within the **PowerRails plugin** by refining the track ordering logic in the **UI**. Previously, power rail tracks from different machines were intermingled, leading to a confusing display. This **refactoring** effort modifies the SQL query within `ui/src/plugins/dev.perfetto.PowerRails/index.ts` to prioritize `machine_id` as the primary sort key. Consequently, all power rails originating from the same machine will now be consistently grouped together before being sorted by name, providing a clearer and more intuitive visualization for users.

This commit introduces a **usability enhancement** for the **diff test framework**, specifically impacting the `--keep-input` option. It modifies the `python/generators/diff_tests/runner.py` script to explicitly print the temporary file path of generated traces directly in the test output. This **feature addition** ensures that developers can easily locate and inspect these trace files, significantly streamlining the debugging and analysis process for diff tests. The `_process_test_result` function is updated to provide this clearer feedback, making the location of retained input files immediately obvious.

This commit introduces a **new convenience option** `--dev-server` to the **`tools/open_trace_in_ui`** utility. This **enhancement** allows developers to directly open trace files within a locally hosted development UI, typically run via `ui/run-dev-server`, rather than the default production environment. The change primarily affects the **developer workflow** for **trace visualization**, streamlining the process of testing UI modifications. It provides a more efficient way for developers to interact with and debug the trace UI during active development.

This commit introduces a **new capability** to the **Perfetto trace processor's Android logcat importer**, allowing it to correctly parse log events that include an explicit year in the `YYYY-MM-DD` format. Previously, the system relied on error-prone year guessing for `MM-DD` dates, which could lead to incorrect timestamps, especially across year boundaries or with system clock issues. The `AndroidLogReader`'s `ParseLine` method now prioritizes the provided year, falling back to the existing guessing logic only if the year is absent, and `DetectFormat` is updated to recognize the new format. This **enhancement** significantly **improves the accuracy of log event timestamping** in Perfetto traces, ensuring more reliable analysis of Android bugreports by addressing a critical limitation in date parsing.

This commit introduces a **new capability** to the **Perfetto SQL standard library** for Linux CPU utilization, enabling the measurement of CPU cycles aggregated by both thread and CPU. A new SQL module, `thread_cpu.sql`, provides the `cpu_cycles_per_thread_per_cpu` table and `cpu_cycles_per_thread_per_cpu_in_interval` function, offering more granular insights into CPU usage on heterogeneous architectures. This change also involves a **refactoring** where existing CPU utilization metrics, such as `cpu_cycles_per_process`, `cpu_cycles`, `cpu_cycles_per_cpu`, and `cpu_cycles_per_thread`, are now derived from this new, more detailed `cpu_cycles_per_thread_per_cpu` module. This enhancement allows users to differentiate and analyze CPU cycles from specific CPUs within a thread, providing a more precise understanding of system performance.

This commit delivers a **bug fix** to the **Perfetto SQL standard library**, specifically within the `linux/cpu/utilization` module, by correcting the calculation of average CPU frequency (`avg_freq`). It addresses an issue where null frequency values, representing unknown CPU frequencies, were erroneously included in the denominator, leading to inaccurate `avg_freq` results and violating expected inequalities. The fix modifies `process.sql`, `system.sql`, and `thread.sql` to properly **exclude null frequencies** from the average calculation, thereby ensuring more reliable and accurate **CPU utilization metrics**. This improves the consistency of performance analysis, with updated test cases reflecting the corrected values.

This commit provides a **bug fix** for **Linux CPU utilization** calculations within the `stdlib` routines, addressing intermediate truncation issues that led to less accurate results. It refactors SQL queries in `process.sql`, `system.sql`, and `thread.sql` by moving division operations outside of `SUM()` aggregations and removing redundant `/ 1000` factors from both numerator and denominator. This change primarily improves the accuracy of `avg_freq` metrics, ensuring more precise data for CPU utilization analysis. The updated `diff_tests` reflect these corrected calculations, enhancing the reliability of the `stdlib`'s performance metrics.