README.md
1# Perf dashboard API
2
3## Authenticating
4The perf dashboard API uses OAuth to authenticate. You must either have a
5Google account or a service account to access the API. See
6[examples](/dashboard/dashboard/api/examples/) directory
7for examples of how to access the API.
8
9## Alerts
10URL pattern for accessing alerts:
11
12 * `/api/alerts?<params>`: Get matching alerts. Supported query parameters:
13 * `key`: Urlsafe alert entity key.
14 * `sheriff`: String. If unspecified, alerts for any sheriff will be
15 returned.
16 * `bug_id`: Set to `''` in order to select untriaged alerts.
17 * `is_improvement`: When omitted, both improvements and regressions are
18 returned. When set to `true`, only improvements are returned. When set to
19 `false`, only regressions are returned.
20 * `recovered`: When omitted, both recovered and unrecovered alerts are
21 returned. When set to `true`, only recovered alerts are returned. When set to
22 `false`, only unrecovered alerts are returned.
23 * `test`: Full slash-separated test path string like
24 `master/bot/test_suite/measurement/test_case`.
25 * `master`, `bot`, `test_suite`: Optional strings.
26 * `limit`: Positive integer. Default 100.
27 * `cursor`: Set to the `next_cursor` returned from a previous request in
28 order to page through results for queries that match more than `limit`
29 alerts.
30 * `min_start_revision`, `max_start_revision`: Integers. If unspecified,
31 alerts at any revisions will be returned.
32 * `min_end_revision`, `max_end_revision`: Integers. If unspecified, alerts
33 at any revisions will be returned.
34 * `min_timestamp`, `max_timestamp`: Datetimes in ISO format.
35 * `report`: Report template id as returned by `/api/report_names`. Multiple
36 `report`s may be specified. Filters alerts to the timeseries referenced by
37 the reports.
38
39The alerts API returns a JSON list of alerts with the following fields:
40
41 * `date`: Date the alert fired in YYYY-MM-DD format
42 * `master`: Buildbot master the alert fired on.
43 * `bot`: Buildbot device type the alert fired on (for example, "nexus 7").
44 * `test`: Test path of the test the alert was fired on. This contains the
45 benchmark/metric/page, like page_cycler/time_to_load/cnn.
46 * `ref_test`: If there was a ref build, the test_path of the ref build.
47 * `testsuite`: Name of the benchmark the alert was fired on.
48 * `recovered`: Whether the dashboard was able to detect that the alert
49 recovered. Note that this is not possible to detect perfectly, as perf
50 graphs are noisy and there may be multiple performance changes. The
51 dashboard errs on the side of false negatives, only marking an alert
52 recovered if it finds a change almost exactly opposite of the one in the
53 alert.
54 * `percent_changed`: The percentage difference before/after the alert.
55 * `absolute_delta`: The difference before/after the alert, in `units`.
56 * `median_before_anomaly`: The median value of the chart segment before the
57 alert, in `units`.
58 * `median_after_anomaly`: The median value of the chart segment after the
59 alert, in `units`.
60 * `units`: The units for the metric that was alerted on (for example,
61 milliseconds).
62 * `improvement`: true if the alert fired on an improvement; false otherwise.
63 (note improvements can be filtered out of the history API with the
64 `improvements` param).
65 * `start_revision`: Start of the revision range where the change occurred.
66 * `end_revision`: End of the revision range where the change occurred.
67 * `dashboard_link`: Link to view the chart with the alert on the perf
68 dashboard.
69 * `bug_id`: The bug linked to the alert in the perf dashboard. -1 means the
70 perf sheriff marked the bug invalid, and -2 means ignored (known issue).
71 An empty bug id means the alert has not been triaged yet.
72 * `group`: Unique id of the group the alert was placed in by the perf
73 dashboard.
74 * `key`: Unique id of the alert, generated by the perf dashboard.
75
76## File New Bug
77
78Permitted sheriffs can file new bugs for alerts by posting to `/api/new_bug`. It
79accepts `owner`, `cc`, `summary`, `description`, zero or more `label`, zero or
80more `component`, zero or more alert `key`. It returns json `{bug_id, error}`.
81
82## Assign Alerts to Existing Bug
83
84Permitted sheriffs can assign alerts to an existing bug by posting to
85`/api/existing_bug`. It accepts `bug` and one or more `key`.
86
87## Bugs
88
89For internal users only, the bugs API gives data about bugs so that it can
90easily be lined up with alerts. URL pattern for accessing bugs:
91
92 * `/api/bugs/id`: Get all the information about bug `id`.
93 * `/api/bugs/recent`: Get an array of performance regression bugs created in
94 the last 5 days.
95
96The bugs API returns the following JSON about the bug:
97
98 * `author`: Email of the issue author
99 * `legacy_bisects`: List of bisects (to be replaced by pinpoint). Each has:
100 * `status`: Job status, such as "started" or "failed
101 * `bot`: Name of the bisector the job ran on,
102 * `buildbucket_link`: Link to buildbucket page with more info
103 * `command`: The command the bisect was run with
104 * `metric`: The metric that was bisected
105 * `cc`: List of emails cc-ed to the issue
106 * `comments`: List of comments. Each has:
107 * `content`: Text of the comment
108 * `author`: Email of the comment author
109 * `published`: Date the comment was published, in milliseconds since 1970
110 * `components`: List of components associated with the issue
111 * `id`: The same id that was passed in
112 * `labels`: List of labels associated with the issue
113 * `published`: Date the comment was published, in milliseconds since 1970
114 * `state`: Issue state (open or closed)
115 * `status`: Status of work on the issue (Assigned, Fixed, etc)
116 * `summary`: The issue summary/title text.
117
118## Timeseries
119
120 URL patterns for accessing timeseries:
121
122 * `/api/list_timeseries/benchmark`: List all the monitored timeseries
123 associated with `benchmark`. Takes an optional `sheriff` param in postdata,
124 which can be set to a name of the seriff rotation or `all` to search for
125 metrics in all rotations. If not specified, the `Chromium Perf Sheriff`
126 rotation is used. Returns an array of test_paths
127 (master/bot/benchmark/metric/page).
128 * `/api/timeseries/test_path`: Return the timeseries data for the given
129 `test_path` as JSON. Can specify `num_days` param in postdata, defaults to
130 30.
131 * `/api/test_suites`: Return an array of names of test suites.
132 * `/api/describe/test_suite`: Return an object containing `measurements`,
133 `bots`, and `cases`, all of which are sorted arrays of strings.
134 * `/api/timeseries2?<params>`: Get timeseries data, alerts, Histograms, and
135 SparseDiagnostics. Post body parameters may include the following:
136 * `test_suite`, `measurement`, `bot`: Required strings from
137 `/api/test_suites` and `/api/describe`.
138 * `test_case`: Optional string from `/api/describe`.
139 * `build_type`: Optional enum `test` (default) or `ref`.
140 * `min_revision`, `max_revision`: Optional point id revision numbers.
141 * `min_timestamp`, `max_timestamp`: Optional ISO 8601 strings.
142 * `columns`: Required comma-separated list of strings. May contain
143 * `revision` produces point ID numbers.
144 * `avg`, `std`, `count`, `max`, `min`, `sum` produce float numbers.
145 * `revisions` produces an object whose keys are names like `r_webkit`
146 and `r_chromium`, and whose values are numbers or strings.
147 * `timestamp` records when the data was uploaded, and produces ISO 8601
148 strings like "2018-07-09T09:58:20.210539"
149 * `alert` produces objects as specified in the Alerts section above.
150 * `histogram` produces [Histogram
151 JSON](https://chromium.googlesource.com/catapult/+/master/docs/histogram-set-json-format.md).
152 * `diagnostics` produces an object whose keys are names (which may be
153 [reserved
154 names](https://chromium.googlesource.com/catapult/+/master/tracing/tracing/value/diagnostics/reserved_infos.py)),
155 and whose values are [Diagnostic
156 JSON](https://chromium.googlesource.com/catapult/+/master/docs/histogram-set-json-format.md#diagnostics).
157 Returns a JSON object containing `units`, `improvement_direction` ("down" or
158 "up"), and "data", which is an array. Elements of the data array are arrays
159 of values corresponding to the `columns` parameter. For example, if
160 `columns=revision,avg,timestamp`, then elements of the data array will be
161 3-tuples like `[123456,42.42,"2018-07-09T09:58:20.210539"]`.
162 * `/api/report/names`: Return an array of objects `{name, id, modified}`.
163 * `/api/report/template`: Creates or modifies report templates.
164 Set `template` to a json object `{rows, statistics}`.
165 Set `name` to a string.
166 Set `owners` to a comma-separated list of email addresses.
167 Optionally set `id` to a template id as returned by `/api/report/names` in
168 order to modify an existing template.
169 Returns the full new list of report templates `{name, id, modified}`.
170 * `/api/report/generate`: Generates reports.
171 Set `id` to a template id as returned by `/api/report/names`.
172 Set `revisions` to a comma-separated list of point id numbers or `latest`.
173