600c23a426
<!-- Please describe your changes on the following line: --> The `energy-profiling` feature was broken at some point when `#![deny(unsafe_code)]` was introduced to the `profile_traits` component. This PR sets `#[allow(unsafe_code)]` on the `energy` module. There is an additional commit (my original intention) to update the profiler logging to use the current `ProfilerCategory` enum values for (typically developer-only) performance/power analysis. --- <!-- Thank you for contributing to Servo! Please replace each `[ ]` by `[X]` when the step is complete, and replace `__` with appropriate data: --> - [X] `./mach build -d` does not report any errors - [X] `./mach test-tidy` does not report any errors - [ ] These changes fix #__ (github issue number if applicable). <!-- Either: --> - [ ] There are tests for these changes OR - [X] These changes do not require tests because it fixes is a compile error for a feature. <!-- Pull requests that do not address these steps are welcome, but they will require additional verification as part of the review process. --> Source-Repo: https://github.com/servo/servo Source-Revision: 1e42e4d9cec1a46a0a3009095c6030425c0a8845 |
||
|---|---|---|
| .. | ||
| Cargo.toml | ||
| README.md | ||
| heartbeats.rs | ||
| lib.rs | ||
| mem.rs | ||
| time.rs | ||
| trace-dump-epilogue-1.html | ||
| trace-dump-epilogue-2.html | ||
| trace-dump-prologue-1.html | ||
| trace-dump-prologue-2.html | ||
| trace-dump.css | ||
| trace-dump.js | ||
| trace_dump.rs | ||
README.md
This crate hosts the Servo profiler.
Its APIs can be found in the profile_traits crate.
Heartbeats
Heartbeats allow fine-grained timing and energy profiling of Servo tasks specified in the ProfilerCategory enum (see the profile_traits::time module).
When enabled, a heartbeat is issued for each profiler category event.
They also compute the average performance and power for three levels of granularity:
- Global: the entire runtime.
- Window: the category's last
Nevents, whereNis the size of a sliding window. - Instant: the category's most recent event.
Enabling
Heartbeats are enabled for categories by setting proper environment variables prior to launching Servo.
For each desired category, set the SERVO_HEARTBEAT_ENABLE_MyCategory environment variable to any value (an empty string will do) where MyCategory is the ProfilerCategory name exactly as it appears in the enum.
For example:
SERVO_HEARTBEAT_ENABLE_LayoutPerform=""
Then set the SERVO_HEARTBEAT_LOG_MyCategory environment variable so Servo knows where to write the results.
For example:
SERVO_HEARTBEAT_LOG_LayoutPerform="/tmp/heartbeat-LayoutPerform.log"
The target directory must already exist and be writeable.
Results are written to the log file every N heartbeats and when the profiler shuts down.
You can optionally specify the size of the sliding window by setting SERVO_HEARTBEAT_WINDOW_MyCategory to a positive integer value.
The default value is 20.
For example:
SERVO_HEARTBEAT_WINDOW_LayoutPerform=20
The window size is also how many heartbeats will be stored in memory.
Log Files
Log files are whitespace-delimited.
HB is the heartbeat number, ordered by when they are registered (not necessarily start or end time!).
The count starts at 0.
Tag is a client-specified identifier for each heartbeat.
Servo does not use this, so the value is always 0.
Work is the amount of work completed for a particular heartbeat and is used in computing performance.
At this time, Servo simply specifies 1 unit of work for each heartbeat.
Time and Energy have Start and End values as captured during runtime.
Time is measured in nanoseconds and energy is measured in microjoules.
Work, Time, and Energy also have Global and Window values which are the summed over the entire runtime and sliding window period, respectively.
Perf (performance) and Pwr (power) have Global, Window, and Instant values as described above.
Energy Profiling
Energy monitoring is hardware and platform-specific, so it is only enabled with the energy-profiling feature.
To use energy profiling, you must have a compatible energymon-default implementation installed to your system as energymon-default-static when building Servo.
Otherwise a default dummy implementation is used.
The library is linked through a chain of dependencies:
- servo::profile_traits
- energymon - Rust abstractions
- energymon-default-sys - Rust bindings to
energymon-default.h- energymon-default-static: A statically linked C library installed to the system that implements
energymon.handenergymon-default.h
- energymon-default-static: A statically linked C library installed to the system that implements
- energymon-default-sys - Rust bindings to
- energymon - Rust abstractions
For instructions on building existing native libraries, visit the energymon project source.
You may also write your own implementation of energymon.h and energymon-default.h and install it as energymon-default-static where pkg-config can find it.
Once you install the proper library, you will need to rebuild the energymon-default-sys crate.
The most straightforward way to do this is to do a clean build of Servo.
To build Servo with the energy-profiling feature enabled, pass --features "energy-profiling" to the mach command, e.g.:
./mach build -r --features "energy-profiling"
When running Servo, you will want to enable the desired Heartbeats to record the results.