electron/docs/api/content-tracing.md

172 lines
5.2 KiB
Markdown
Raw Normal View History

# contentTracing
2014-07-31 07:40:40 +00:00
2016-04-22 17:30:49 +00:00
> Collect tracing data from Chromium's content module for finding performance
bottlenecks and slow operations.
This module does not include a web interface so you need to open
`chrome://tracing/` in a Chrome browser and load the generated file to view the
result.
2014-07-31 07:40:40 +00:00
```javascript
const {contentTracing} = require('electron')
2015-08-28 17:50:30 +00:00
const options = {
categoryFilter: '*',
traceOptions: 'record-until-full,enable-sampling'
}
contentTracing.startRecording(options, () => {
console.log('Tracing started')
2014-07-31 07:40:40 +00:00
setTimeout(() => {
contentTracing.stopRecording('', (path) => {
console.log('Tracing data recorded to ' + path)
})
}, 5000)
})
2014-07-31 07:40:40 +00:00
```
2015-08-25 11:49:48 +00:00
## Methods
2016-04-26 17:28:20 +00:00
The `contentTracing` module has the following methods:
2015-08-25 11:49:48 +00:00
### `contentTracing.getCategories(callback)`
2014-07-31 07:40:40 +00:00
* `callback` Function
2016-10-13 06:30:57 +00:00
* `categories` String[]
2014-07-31 07:40:40 +00:00
Get a set of category groups. The category groups can change as new code paths
are reached.
2015-08-26 21:56:00 +00:00
Once all child processes have acknowledged the `getCategories` request the
`callback` is invoked with an array of category groups.
2014-07-31 07:40:40 +00:00
2015-09-02 07:16:49 +00:00
### `contentTracing.startRecording(options, callback)`
2014-07-31 07:40:40 +00:00
2015-09-02 07:16:49 +00:00
* `options` Object
* `categoryFilter` String
* `traceOptions` String
2014-07-31 07:40:40 +00:00
* `callback` Function
Start recording on all processes.
2015-08-25 11:49:48 +00:00
Recording begins immediately locally and asynchronously on child processes
2015-08-27 15:11:51 +00:00
as soon as they receive the EnableRecording request. The `callback` will be
called once all child processes have acknowledged the `startRecording` request.
2014-07-31 07:40:40 +00:00
`categoryFilter` is a filter to control what category groups should be
traced. A filter can have an optional `-` prefix to exclude category groups
that contain a matching category. Having both included and excluded
2015-05-23 22:44:58 +00:00
category patterns in the same list is not supported.
2014-07-31 07:40:40 +00:00
Examples:
* `test_MyTest*`,
* `test_MyTest*,test_OtherStuff`,
* `"-excluded_category1,-excluded_category2`
2015-08-25 11:49:48 +00:00
`traceOptions` controls what kind of tracing is enabled, it is a comma-delimited
list. Possible options are:
2015-08-04 20:12:57 +00:00
* `record-until-full`
* `record-continuously`
* `trace-to-console`
* `enable-sampling`
* `enable-systrace`
The first 3 options are trace recoding modes and hence mutually exclusive.
If more than one trace recording modes appear in the `traceOptions` string,
2015-08-27 15:11:51 +00:00
the last one takes precedence. If none of the trace recording modes are
2015-08-26 21:56:00 +00:00
specified, recording mode is `record-until-full`.
2015-08-04 20:12:57 +00:00
2015-08-27 15:11:51 +00:00
The trace option will first be reset to the default option (`record_mode` set to
`record-until-full`, `enable_sampling` and `enable_systrace` set to `false`)
2015-08-04 20:12:57 +00:00
before options parsed from `traceOptions` are applied on it.
2014-07-31 07:40:40 +00:00
### `contentTracing.stopRecording(resultFilePath, callback)`
2014-07-31 07:40:40 +00:00
* `resultFilePath` String
* `callback` Function
2016-10-13 06:30:57 +00:00
* `resultFilePath` String
2014-07-31 07:40:40 +00:00
Stop recording on all processes.
2015-08-27 15:11:51 +00:00
Child processes typically cache trace data and only rarely flush and send
trace data back to the main process. This helps to minimize the runtime overhead
of tracing since sending trace data over IPC can be an expensive operation. So,
to end tracing, we must asynchronously ask all child processes to flush any
pending trace data.
2014-07-31 07:40:40 +00:00
2015-08-26 21:56:00 +00:00
Once all child processes have acknowledged the `stopRecording` request,
`callback` will be called with a file that contains the traced data.
2014-07-31 07:40:40 +00:00
2015-08-25 11:49:48 +00:00
Trace data will be written into `resultFilePath` if it is not empty or into a
2014-07-31 07:40:40 +00:00
temporary file. The actual file path will be passed to `callback` if it's not
2015-08-25 11:49:48 +00:00
`null`.
2014-07-31 07:40:40 +00:00
2015-09-02 07:16:49 +00:00
### `contentTracing.startMonitoring(options, callback)`
2014-07-31 07:40:40 +00:00
2015-09-02 07:16:49 +00:00
* `options` Object
* `categoryFilter` String
* `traceOptions` String
2014-07-31 07:40:40 +00:00
* `callback` Function
Start monitoring on all processes.
2015-08-25 11:49:48 +00:00
Monitoring begins immediately locally and asynchronously on child processes as
2014-07-31 07:40:40 +00:00
soon as they receive the `startMonitoring` request.
2015-08-26 21:56:00 +00:00
Once all child processes have acknowledged the `startMonitoring` request the
2015-08-25 11:49:48 +00:00
`callback` will be called.
2014-07-31 07:40:40 +00:00
### `contentTracing.stopMonitoring(callback)`
2014-07-31 07:40:40 +00:00
* `callback` Function
Stop monitoring on all processes.
2015-08-26 21:56:00 +00:00
Once all child processes have acknowledged the `stopMonitoring` request the
2015-08-25 12:16:20 +00:00
`callback` is called.
2014-07-31 07:40:40 +00:00
### `contentTracing.captureMonitoringSnapshot(resultFilePath, callback)`
2014-07-31 07:40:40 +00:00
* `resultFilePath` String
* `callback` Function
2016-10-13 06:30:57 +00:00
* `resultFilePath`
2014-07-31 07:40:40 +00:00
Get the current monitoring traced data.
2015-08-27 15:11:51 +00:00
Child processes typically cache trace data and only rarely flush and send
2015-08-26 21:56:00 +00:00
trace data back to the main process. This is because it may be an expensive
2015-08-25 11:49:48 +00:00
operation to send the trace data over IPC and we would like to avoid unneeded
2015-08-25 12:16:20 +00:00
runtime overhead from tracing. So, to end tracing, we must asynchronously ask
all child processes to flush any pending trace data.
2014-07-31 07:40:40 +00:00
2015-08-26 21:56:00 +00:00
Once all child processes have acknowledged the `captureMonitoringSnapshot`
request the `callback` will be called with a file that contains the traced data.
2014-07-31 07:40:40 +00:00
### `contentTracing.getTraceBufferUsage(callback)`
2014-07-31 07:40:40 +00:00
* `callback` Function
2016-10-13 06:30:57 +00:00
* `value` Number
* `percentage` Number
2014-07-31 07:40:40 +00:00
2015-08-25 12:16:20 +00:00
Get the maximum usage across processes of trace buffer as a percentage of the
full state. When the TraceBufferUsage value is determined the `callback` is
called.
2014-07-31 07:40:40 +00:00
### `contentTracing.setWatchEvent(categoryName, eventName, callback)`
2014-07-31 07:40:40 +00:00
* `categoryName` String
* `eventName` String
* `callback` Function
`callback` will be called every time the given event occurs on any
2015-03-10 23:02:22 +00:00
process.
2014-07-31 07:40:40 +00:00
### `contentTracing.cancelWatchEvent()`
2014-07-31 07:40:40 +00:00
2015-08-27 15:11:51 +00:00
Cancel the watch event. This may lead to a race condition with the watch event
callback if tracing is enabled.