Update data/params after Bugzilla 4.2.11 upgrade
[WebKit-https.git] / Websites / perf.webkit.org / ReadMe.md
1 # Concepts
2
3 ## Platform
4
5 A platform is an environmental configuration under which performance tests run. This is typically
6 an operating system such as Lion, Mountain Lion, or Windows 7.
7
8 ## Builder
9
10 A builder is a physical machine that submits a result of one or more tests to one or more platforms.
11 Each builder should have a password it uses to submit the results to this application, and it may also
12 have a URL associated with it.
13
14 ## Build
15
16 A build is a single run of tests on a given builder. It's possible for a single build to have ran multiple
17 tests on multiple platforms.
18
19 ## Test Metric
20
21 A test metric is a type of measurement a test makes. A single test may measure multiple metrics such as
22 Time (ms), Malloc (bytes), and JSHeap (bytes). The mapping from metrics to units is a function
23 (in mathematical sense).
24
25 ## Test Configuration
26
27 A test configuration is a combination of a test metric, a platform, and a configuration type: "current",
28 "baseline", or "target". With metric, configuration creates a three-level tree structure under a test as follows:
29
30 - MyTest (Test 1)
31     - Time (Metric 1)
32         - Lion : current (Configuration 1)
33         - Lion : baseline (Configuration 2)
34         - Lion : target (Configuration 3)
35         - Mountain Lion : current (Configuration 4)
36         - Mountain Lion : baseline (Configuration 5)
37         - Mountain Lion : target (Configuration 6)
38     - Malloc (Metric 2)
39         - Lion : current (Configuration 7)
40         - Lion : baseline (Configuration 8)
41         - Lion : target (Configuration 9)
42         - Mountain Lion : current (Configuration 10)
43         - Mountain Lion : baseline (Configuration 11)
44         - Mountain Lion : target (Configuration 12)
45 - AnotherTest (Test 2)
46     - Time (Metric 3)
47         - Lion : current (Configuration 13)
48         - Mountain Lion : current (Configuration 14)
49
50 ## Run and Iteration
51
52 A run is a ordered list of values obtained for a single configuration on a single build. For example, a Lion
53 builder may execute MyTest 10 times, i.e. 10 iterations, and create a single run after computing the arithmetic
54 mean of 10 values obtained in this process. Each run has associated iterations, which represents an individual
55 measurement of the same configuration (of a single test metric) in the run.
56
57 ## Aggregation and Aggregator
58
59 Aggregation is a process by which a test with child tests synthetically generates results for itself using
60 results of sub tests. For example, we may have a page loading test (PageLoadingTest), which loads
61 www.webkit.org and www.mozilla.org as follows:
62
63 - PageLoadingTest (Test 1)
64     - www.webkit.org (Test 2)
65     - www.mozilla.org (Test 3)
66
67 (Note that PageLoadingTest, www.webkit.org, and www.mozilla.org each has its own metrics and configurations,
68 which are not shown here.)
69
70 Then results for a metric, e.g. Time, of PageLoadingTest could be generated from results of the same metric in
71 subtests, namely www.webkit.org and www.mozilla.org. The process is called "aggregation", and the exact nature of
72 the aggregation is defined in terms of an aggregator. All aggregators are written in JavaScript.
73
74 The aggregator for arithmetic mean could be implemented as:
75     
76     values.reduce(function (a, b) { return a + b; }) / values.length;
77
78 When a builder reports a result JSON to the application, the background process automatically schedules a job
79 to aggregate results for all tests specified in the JSON. The aggregation can also be triggered manually on
80 `/admin/tests`.
81
82 Reporting Results
83 =================
84
85 To submit the results of a new test to an instance of the app, you need the following:
86
87  - A builder already added on `/admin/builders`
88  - A script that submits a JSON payload of the supported format via a HTTP/HTTPS request to `/api/report`
89
90 JSON Format
91 -----------
92
93 The JSON submitted to `/api/report` should be an array of dictionaries, each of which should
94 contain the following key-value pairs representing a single run of tests on a single build:
95
96 - `builderName` - The name of a builder present on `/admin/builders`.
97 - `builderPassword` - The password associated with the builder.
98 - `buildNumber` - The string that uniquely identifies a given build on the builder.
99 - `buildTime` - The time at which this build started in **UTC** (Use ISO time format such as
100    2013-01-31T22:22:12.121051). This is completely independent of timestamp of repository revisions.
101 - `platform` - The human-readable name of a platform such as `Mountain Lion` or `Windows 7`.
102 - `revisions` - A dictionary that maps a repository name to a dictionary with "revision" and optionally
103    "timestamp" as keys each of which maps to, respectively, the revision in **string** associated with
104    the build and the times at which the revision was committed to the repository respectively.
105    e.g. `{"WebKit": {"revision": "123", "timestamp": "2001-09-10T17:53:19.000000Z"}}`
106 - `tests` - A dictionary that maps a test name to a dictionary that represents a test. The value of a test
107    itself is a dictionary with the following keys:
108     - `metrics` - A dictionary that maps a metric name to a dictionary of configuration types to an array of
109       iteration values. e.g. `{"Time": {"current": [629.1, 654.8, 598.9], "target": [544, 585.1, 556]}}`
110       When a metric represents an aggregated value, it should be an array of aggregator names instead. e.g.
111       `{"Time": ["Arithmetic", "Geometric"]}` **This format may change in near future**.
112     - `url` - The URL of the test. This value should not change over time as only the latest value is stored
113         in the application.
114     - `tests` - A dictionary of tests; the same format as this dictionary.
115
116 A sample JSON:
117
118 [{
119     "buildNumber": "651",
120     "buildTime": "2013-01-31T22:22:12.121051",
121     "builderName": "bot-111",
122     "builderPassword": "********",
123     "platform": "Mountain Lion",
124     "revisions": {
125         "OS X": {
126             "revision": "10.8.2"
127         },
128         "WebKit": {
129             "revision": "141469",
130             "timestamp": "2013-01-31T20:55:15.452267Z"
131         }
132     },
133     "tests": {
134         "PageLoadingTest": {
135             "metrics": {
136                 "Time": [
137                     "Arithmetic",
138                     "Geometric"
139                 ]
140             },
141             "tests": {
142                 "webkit.org": {
143                     "metrics": {
144                         "Time": {
145                             "current": [
146                                 629.1,
147                                 654.8,
148                                 598.9
149                             ]
150                         }
151                     }
152                 },
153                 "url": "http://www.webkit.org/"
154             }
155         }
156     }
157 }]
158
159 FIXME: Add a section describing how the application is structured.