Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Copyright 2017 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package android.webkit; |
| 18 | |
| 19 | import android.annotation.IntDef; |
| 20 | import android.annotation.NonNull; |
| 21 | |
| 22 | import java.lang.annotation.Retention; |
| 23 | import java.lang.annotation.RetentionPolicy; |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 24 | import java.util.ArrayList; |
| 25 | import java.util.Collection; |
| 26 | import java.util.List; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 27 | |
| 28 | /** |
| 29 | * Holds tracing configuration information and predefined settings. |
| 30 | */ |
| 31 | public class TracingConfig { |
| 32 | |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 33 | private @PredefinedCategories int mPredefinedCategories; |
| 34 | private final List<String> mCustomIncludedCategories = new ArrayList<String>(); |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 35 | private @TracingMode int mTracingMode; |
| 36 | |
| 37 | /** @hide */ |
Tim Volodine | 1a07ccc | 2018-03-19 20:07:23 +0000 | [diff] [blame] | 38 | @IntDef(flag = true, value = {CATEGORIES_NONE, CATEGORIES_ALL, CATEGORIES_ANDROID_WEBVIEW, |
| 39 | CATEGORIES_WEB_DEVELOPER, CATEGORIES_INPUT_LATENCY, CATEGORIES_RENDERING, |
| 40 | CATEGORIES_JAVASCRIPT_AND_RENDERING, CATEGORIES_FRAME_VIEWER}) |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 41 | @Retention(RetentionPolicy.SOURCE) |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 42 | public @interface PredefinedCategories {} |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 43 | |
| 44 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 45 | * Indicates that there are no predefined categories. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 46 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 47 | public static final int CATEGORIES_NONE = 0; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 48 | |
| 49 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 50 | * Predefined set of categories, includes all categories enabled by default in chromium. |
| 51 | * Use with caution: this setting may produce large trace output. |
| 52 | */ |
| 53 | public static final int CATEGORIES_ALL = 1 << 0; |
| 54 | |
| 55 | /** |
| 56 | * Predefined set of categories typically useful for analyzing WebViews. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 57 | * Typically includes "android_webview" and "Java" categories. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 58 | */ |
| 59 | public static final int CATEGORIES_ANDROID_WEBVIEW = 1 << 1; |
| 60 | |
| 61 | /** |
| 62 | * Predefined set of categories typically useful for web developers. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 63 | * Typically includes "blink", "compositor", "renderer.scheduler" and "v8" categories. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 64 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 65 | public static final int CATEGORIES_WEB_DEVELOPER = 1 << 2; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 66 | |
| 67 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 68 | * Predefined set of categories for analyzing input latency issues. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 69 | * Typically includes "input", "renderer.scheduler" categories. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 70 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 71 | public static final int CATEGORIES_INPUT_LATENCY = 1 << 3; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 72 | |
| 73 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 74 | * Predefined set of categories for analyzing rendering issues. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 75 | * Typically includes "blink", "compositor" and "gpu" categories. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 76 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 77 | public static final int CATEGORIES_RENDERING = 1 << 4; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 78 | |
| 79 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 80 | * Predefined set of categories for analyzing javascript and rendering issues. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 81 | * Typically includes "blink", "compositor", "gpu", "renderer.scheduler" and "v8" categories. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 82 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 83 | public static final int CATEGORIES_JAVASCRIPT_AND_RENDERING = 1 << 5; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 84 | |
| 85 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 86 | * Predefined set of categories for studying difficult rendering performance problems. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 87 | * Typically includes "blink", "compositor", "gpu", "renderer.scheduler", "v8" and |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 88 | * some other compositor categories which are disabled by default. |
| 89 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 90 | public static final int CATEGORIES_FRAME_VIEWER = 1 << 6; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 91 | |
| 92 | /** @hide */ |
Tim Volodine | 1a07ccc | 2018-03-19 20:07:23 +0000 | [diff] [blame] | 93 | @IntDef({RECORD_UNTIL_FULL, RECORD_CONTINUOUSLY}) |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 94 | @Retention(RetentionPolicy.SOURCE) |
| 95 | public @interface TracingMode {} |
| 96 | |
| 97 | /** |
Tim Volodine | 1a07ccc | 2018-03-19 20:07:23 +0000 | [diff] [blame] | 98 | * Record trace events until the internal tracing buffer is full. |
| 99 | * |
| 100 | * Typically the buffer memory usage is larger than {@link #RECORD_CONTINUOUSLY}. |
| 101 | * Depending on the implementation typically allows up to 256k events to be stored. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 102 | */ |
| 103 | public static final int RECORD_UNTIL_FULL = 0; |
| 104 | |
| 105 | /** |
Tim Volodine | 1a07ccc | 2018-03-19 20:07:23 +0000 | [diff] [blame] | 106 | * Record trace events continuously using an internal ring buffer. Default tracing mode. |
| 107 | * |
| 108 | * Overwrites old events if they exceed buffer capacity. Uses less memory than the |
| 109 | * {@link #RECORD_UNTIL_FULL} mode. Depending on the implementation typically allows |
| 110 | * up to 64k events to be stored. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 111 | */ |
| 112 | public static final int RECORD_CONTINUOUSLY = 1; |
| 113 | |
| 114 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 115 | * @hide |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 116 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 117 | public TracingConfig(@PredefinedCategories int predefinedCategories, |
| 118 | @NonNull List<String> customIncludedCategories, |
| 119 | @TracingMode int tracingMode) { |
| 120 | mPredefinedCategories = predefinedCategories; |
| 121 | mCustomIncludedCategories.addAll(customIncludedCategories); |
| 122 | mTracingMode = tracingMode; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 123 | } |
| 124 | |
| 125 | /** |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 126 | * Returns a bitmask of the predefined category sets of this configuration. |
| 127 | * |
| 128 | * @return Bitmask of predefined category sets. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 129 | */ |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 130 | @PredefinedCategories |
| 131 | public int getPredefinedCategories() { |
| 132 | return mPredefinedCategories; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 133 | } |
| 134 | |
| 135 | /** |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 136 | * Returns the list of included custom category patterns for this configuration. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 137 | * |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 138 | * @return Empty list if no custom category patterns are specified. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 139 | */ |
| 140 | @NonNull |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 141 | public List<String> getCustomIncludedCategories() { |
| 142 | return mCustomIncludedCategories; |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 143 | } |
| 144 | |
| 145 | /** |
| 146 | * Returns the tracing mode of this configuration. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 147 | * |
| 148 | * @return The tracing mode of this configuration. |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 149 | */ |
| 150 | @TracingMode |
| 151 | public int getTracingMode() { |
| 152 | return mTracingMode; |
| 153 | } |
| 154 | |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 155 | /** |
| 156 | * Builder used to create {@link TracingConfig} objects. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 157 | * <p> |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 158 | * Examples: |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 159 | * <pre class="prettyprint"> |
| 160 | * // Create a configuration with default options: {@link #CATEGORIES_NONE}, |
| 161 | * // {@link #RECORD_CONTINUOUSLY}. |
| 162 | * <code>new TracingConfig.Builder().build()</code> |
| 163 | * |
| 164 | * // Record trace events from the "web developer" predefined category sets. |
| 165 | * // Uses a ring buffer (the default {@link #RECORD_CONTINUOUSLY} mode) for |
| 166 | * // internal storage during tracing. |
| 167 | * <code>new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER).build()</code> |
| 168 | * |
| 169 | * // Record trace events from the "rendering" and "input latency" predefined |
| 170 | * // category sets. |
| 171 | * <code>new TracingConfig.Builder().addCategories(CATEGORIES_RENDERING, |
| 172 | * CATEGORIES_INPUT_LATENCY).build()</code> |
| 173 | * |
| 174 | * // Record only the trace events from the "browser" category. |
| 175 | * <code>new TracingConfig.Builder().addCategories("browser").build()</code> |
| 176 | * |
| 177 | * // Record only the trace events matching the "blink*" and "renderer*" patterns |
| 178 | * // (e.g. "blink.animations", "renderer_host" and "renderer.scheduler" categories). |
| 179 | * <code>new TracingConfig.Builder().addCategories("blink*","renderer*").build()</code> |
| 180 | * |
| 181 | * // Record events from the "web developer" predefined category set and events from |
| 182 | * // the "disabled-by-default-v8.gc" category to understand where garbage collection |
| 183 | * // is being triggered. Uses a limited size buffer for internal storage during tracing. |
| 184 | * <code>new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER) |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 185 | * .addCategories("disabled-by-default-v8.gc") |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 186 | * .setTracingMode(RECORD_UNTIL_FULL).build()</code> |
| 187 | * </pre> |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 188 | */ |
| 189 | public static class Builder { |
| 190 | private @PredefinedCategories int mPredefinedCategories = CATEGORIES_NONE; |
| 191 | private final List<String> mCustomIncludedCategories = new ArrayList<String>(); |
Tim Volodine | 1a07ccc | 2018-03-19 20:07:23 +0000 | [diff] [blame] | 192 | private @TracingMode int mTracingMode = RECORD_CONTINUOUSLY; |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 193 | |
| 194 | /** |
| 195 | * Default constructor for Builder. |
| 196 | */ |
| 197 | public Builder() {} |
| 198 | |
| 199 | /** |
| 200 | * Build {@link TracingConfig} using the current settings. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 201 | * |
| 202 | * @return The {@link TracingConfig} with the current settings. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 203 | */ |
| 204 | public TracingConfig build() { |
| 205 | return new TracingConfig(mPredefinedCategories, mCustomIncludedCategories, |
| 206 | mTracingMode); |
| 207 | } |
| 208 | |
| 209 | /** |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 210 | * Adds predefined sets of categories to be included in the trace output. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 211 | * |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 212 | * A predefined category set can be one of {@link #CATEGORIES_NONE}, |
| 213 | * {@link #CATEGORIES_ALL}, {@link #CATEGORIES_ANDROID_WEBVIEW}, |
| 214 | * {@link #CATEGORIES_WEB_DEVELOPER}, {@link #CATEGORIES_INPUT_LATENCY}, |
| 215 | * {@link #CATEGORIES_RENDERING}, {@link #CATEGORIES_JAVASCRIPT_AND_RENDERING} or |
| 216 | * {@link #CATEGORIES_FRAME_VIEWER}. |
| 217 | * |
| 218 | * @param predefinedCategories A list or bitmask of predefined category sets. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 219 | * @return The builder to facilitate chaining. |
| 220 | */ |
| 221 | public Builder addCategories(@PredefinedCategories int... predefinedCategories) { |
| 222 | for (int categorySet : predefinedCategories) { |
| 223 | mPredefinedCategories |= categorySet; |
| 224 | } |
| 225 | return this; |
| 226 | } |
| 227 | |
| 228 | /** |
| 229 | * Adds custom categories to be included in trace output. |
| 230 | * |
| 231 | * Note that the categories are defined by the currently-in-use version of WebView. They |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 232 | * live in chromium code and are not part of the Android API. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 233 | * See <a href="https://www.chromium.org/developers/how-tos/trace-event-profiling-tool"> |
| 234 | * chromium documentation on tracing</a> for more details. |
| 235 | * |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 236 | * @param categories A list of category patterns. A category pattern can contain wildcards, |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 237 | * e.g. "blink*" or full category name e.g. "renderer.scheduler". |
| 238 | * @return The builder to facilitate chaining. |
| 239 | */ |
| 240 | public Builder addCategories(String... categories) { |
| 241 | for (String category: categories) { |
| 242 | mCustomIncludedCategories.add(category); |
| 243 | } |
| 244 | return this; |
| 245 | } |
| 246 | |
| 247 | /** |
| 248 | * Adds custom categories to be included in trace output. |
| 249 | * |
| 250 | * Same as {@link #addCategories(String...)} but allows to pass a Collection as a parameter. |
| 251 | * |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 252 | * @param categories A list of category patterns. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 253 | * @return The builder to facilitate chaining. |
| 254 | */ |
| 255 | public Builder addCategories(Collection<String> categories) { |
| 256 | mCustomIncludedCategories.addAll(categories); |
| 257 | return this; |
| 258 | } |
| 259 | |
| 260 | /** |
| 261 | * Sets the tracing mode for this configuration. |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 262 | * When tracingMode is not set explicitly, the default is {@link #RECORD_CONTINUOUSLY}. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 263 | * |
Tim Volodine | 90980b4 | 2018-04-04 17:49:28 +0100 | [diff] [blame] | 264 | * @param tracingMode The tracing mode to use, one of {@link #RECORD_UNTIL_FULL} or |
Tim Volodine | 1a07ccc | 2018-03-19 20:07:23 +0000 | [diff] [blame] | 265 | * {@link #RECORD_CONTINUOUSLY}. |
Tim Volodine | 88604f2 | 2018-01-18 20:14:08 +0000 | [diff] [blame] | 266 | * @return The builder to facilitate chaining. |
| 267 | */ |
| 268 | public Builder setTracingMode(@TracingMode int tracingMode) { |
| 269 | mTracingMode = tracingMode; |
| 270 | return this; |
| 271 | } |
| 272 | } |
| 273 | |
Tim Volodine | c809542 | 2017-11-10 21:07:36 +0000 | [diff] [blame] | 274 | } |