mirror of
https://github.com/servo/servo.git
synced 2025-06-21 23:59:00 +01:00
92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
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](https://github.com/energymon/energymon).
|
|
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.:
|
|
|
|
```sh
|
|
./mach build -r --features "energy-profiling"
|
|
```
|
|
|
|
When running Servo, you will want to enable the desired Heartbeats to record the results.
|