Logging‎ > ‎

Performance Log

ChromeDriver supports performance logging, from which you can get events of domains "Timeline", "Network", and "Page", as well as trace data for specified trace categories.

Enabling Performance Log

Performance logging is NOT enabled by default. So when creating a new session, you have to enable it.

DesiredCapabilities cap = DesiredCapabilities.chrome();
LoggingPreferences logPrefs = new LoggingPreferences();
logPrefs.enable(LogType.PERFORMANCE, Level.ALL);
cap.setCapability(CapabilityType.LOGGING_PREFS, logPrefs);
RemoteWebDriver driver = new RemoteWebDriver(new URL("http://127.0.0.1:9515"), cap);

When enabled, the performance log will collect Timeline, Network, and Page events. To also enable tracing, or to customize performance logging, see the sections below.

View a complete example of performance logging with default options (credit: Michael Klepikov).

Angular Benchpress also uses performance logging.

Tracing and Custom Logging

If you wish to customize performance logging, e.g. to enable tracing, you can use the perfLoggingPrefs capability (via ChromeOptions). Tracing can be enabled by specifying one or more Chrome trace categories. For more information about Chrome tracing, see here.

When tracing is enabled, the Timeline domain will be implicitly disabled. Note that you still need to enable the performance log with the loggingPrefs capability.

DesiredCapabilities cap = DesiredCapabilities.chrome();
LoggingPreferences logPrefs = new LoggingPreferences();
logPrefs.enable(LogType.PERFORMANCE, Level.ALL);
cap.setCapability(CapabilityType.LOGGING_PREFS, logPrefs);

Map<String, Object> perfLogPrefs = new HashMap<String, Object>();
prefs.put("traceCategories", "browser,devtools.timeline,devtools"); // comma-separated trace categories
ChromeOptions options = new ChromeOptions();
options.setExperimentalOption("perfLoggingPrefs", prefs);
caps.setCapability(ChromeOptions.CAPABILITY, options);

RemoteWebDriver driver = new RemoteWebDriver(new URL("http://127.0.0.1:9515"), cap);

You can also use perfLoggingPrefs to enable or disable the Timeline, Network, and Page domains individually. For example, you can explicitly enable the Timeline domain while tracing:

...
Map<String, Object> perfLogPrefs = new HashMap<String, Object>();
prefs.put("traceCategories", "browser,devtools.timeline,devtools");
prefs.put("enableTimeline", true);
ChromeOptions options = new ChromeOptions();
options.setExperimentalOption("perfLoggingPrefs", prefs);
caps.setCapability(ChromeOptions.CAPABILITY, options);
...

A note about tracing

If tracing is enabled, ChromeDriver will start a browser-wide trace when Chrome is launched, and will continue tracing until Chrome closes. When a trace is running, Chrome buffers trace events in memory until the trace is stopped. Once the trace buffer is full, trace events will no longer be recorded. To avoid a full buffer (and thus lost trace data), ChromeDriver will periodically stop the current trace, collect the buffered events, and re-start tracing at certain points during a test.

Collecting trace events can add overhead to a test, so ChromeDriver only collects trace events at appropriate points during a test. Currently, trace events are only collected on page navigation events and when any ChromeDriver log (e.g. the performance log) is requested. There is always a possibility that the buffer will still fill, so ChromeDriver monitors the buffer usage for supported Chrome versions (r263512 and later). If the buffer fills, ChromeDriver will log a warning and will add an entry to the performance log, as described below.

Collecting Log Entries

In the test, you can get performance log entries as below. See the WebDriver logging documentation for more information.

for (LogEntry entry : driver.manage().logs().get(LogType.PERFORMANCE)) {
    System.out.println(entry.toString());
}

Each entry is a JSON string of the following structure:

{
    "webview": <originating WebView ID>,
    "message": { "method": "...", "params": { ... }} // DevTools message.
}

The method value is the method of the DevTools event (see Chrome Remote Debugging Protocol documentation). For example, Timeline events will have a method of Timeline.eventRecorded for all versions of the protocol up to and including version 1.1 (the latest at the time this was written).

Trace Log Entries

Tracing is not part of the published DevTools protocol as of version 1.1, so details are provided below.

All trace events will have a webview value of “browser” since the events are collected browser-wide.

There are two possible trace event methods:
  • tracing.dataCollected: params will be a single trace event in the form of a dictionary
  • tracing.bufferUsage: params will contain a single error key, with a message indicating that the DevTools trace buffer filled during the test, as described above
Below is an example trace event:

{
    "webview":"browser",
    "message":{
        "method":"Tracing.dataCollected",
        "params":{
            "args":{"layerTreeId":1},
            "cat":"cc,devtools",
            "name":"DrawFrame",
            "ph":"i",
            "pid":11405,
            "s":"t",
            "tid":11405,
            "ts":3846117219.0,
            "tts":1134680
        }
    }
}