gecko-dev/servo/components/profile
Anthony Ramine 64c09a7eda servo: Merge #12828 - Update serde to 0.8 (fixes #12659) (from nox:serde); r=Ms2ger
Source-Repo: https://github.com/servo/servo
Source-Revision: 9abe9e450b54ef9151bbee1aa0bd2dedb685fa7a
2016-08-12 12:23:10 -05:00
..
Cargo.toml servo: Merge #12828 - Update serde to 0.8 (fixes #12659) (from nox:serde); r=Ms2ger 2016-08-12 12:23:10 -05:00
heartbeats.rs servo: Merge #11785 - Update heartbeats-simple to 0.3.0 (from connorimes:update-hbs-0.3.0); r=metajack 2016-06-20 15:28:22 -05:00
lib.rs servo: Merge #12712 - Update Rust to 1.12.0-nightly (545a3a94f 2016-08-04) (from servo:rustup); r=Ms2ger 2016-08-05 07:46:27 -05:00
mem.rs servo: Merge #11930 - Remove some util stuff (from nox:die-util-die); r=SimonSapin 2016-06-29 15:37:42 -05:00
README.md servo: Merge #7593 - Add documentation to profile crate on Heartbeats and energy-profiling (from connorimes:energy-profiling-doc); r=larsbergstrom 2015-09-10 11:29:29 -06:00
time.rs servo: Merge #12327 - Profile stats (from malisas:profile-stats); r=jdm 2016-07-07 21:08:50 -07:00
trace_dump.rs servo: Merge #11329 - Report use statements that use {} with only one entry (from c-rhodes:11320); r=jdm 2016-05-27 07:11:17 -05:00
trace-dump-epilogue-1.html servo: Merge #10694 - Add a method for dumping profiles as self-contained HTML w/ timeline visualization (from fitzgen:profile-traces-to-file); r=SimonSapin 2016-04-28 02:47:35 -07:00
trace-dump-epilogue-2.html servo: Merge #10694 - Add a method for dumping profiles as self-contained HTML w/ timeline visualization (from fitzgen:profile-traces-to-file); r=SimonSapin 2016-04-28 02:47:35 -07:00
trace-dump-prologue-1.html servo: Merge #10694 - Add a method for dumping profiles as self-contained HTML w/ timeline visualization (from fitzgen:profile-traces-to-file); r=SimonSapin 2016-04-28 02:47:35 -07:00
trace-dump-prologue-2.html servo: Merge #10694 - Add a method for dumping profiles as self-contained HTML w/ timeline visualization (from fitzgen:profile-traces-to-file); r=SimonSapin 2016-04-28 02:47:35 -07:00
trace-dump.css servo: Merge #11098 - Update trace-dump.{js,css} from upstream (from fitzgen:update-trace-dump); r=jdm 2016-05-10 06:34:32 -07:00
trace-dump.js servo: Merge #11098 - Update trace-dump.{js,css} from upstream (from fitzgen:update-trace-dump); r=jdm 2016-05-10 06:34:32 -07:00

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 N events, where N is 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.h and energymon-default.h

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.