1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
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.
|
