Skip to main content

contentTracing

Collect tracing data from Chromium to find performance bottlenecks and slow operations.

Process: Main

This module does not include a web interface. Traces are recorded in the Perfetto protobuf format; to view them, open them in the Perfetto UI.

note

You should not use this module until the ready event of the app module is emitted.

const { app, contentTracing } = require('electron')

app.whenReady().then(async () => {
  await contentTracing.startRecording({
    included_categories: ['*']
  })
  console.log('Tracing started')
  await new Promise((resolve) => setTimeout(resolve, 5000))
  const path = await contentTracing.stopRecording()
  console.log('Tracing data recorded to ' + path)
})

Methods​

The contentTracing module has the following methods:

contentTracing.getCategories()​

History

Returns Promise<string[]> - resolves with an array of category groups once all child processes have acknowledged the getCategories request

Get a set of category groups. The category groups can change as new code paths are reached. See also the list of built-in tracing categories.

NOTE: Electron adds a non-default tracing category called "electron". This category can be used to capture Electron-specific tracing events.

contentTracing.startRecording(options)​

History
Version(s)Changes
None

The options parameter now accepts TraceConfig in addition to TraceCategoriesAndOptions.

None

This function now returns a callbackPromise<void>.

>=45.0.0

Added the nativeHeapProfiling option to enable native heap profiling.

Returns Promise<void> - resolved once all child processes have acknowledged the startRecording request.

Start recording on all processes.

Recording begins immediately locally and asynchronously on child processes as soon as they receive the EnableRecording request.

If a recording is already running, the promise will be immediately resolved, as only one trace operation can be in progress at a time. If options.nativeHeapProfiling is set while a recording is already running, the promise is rejected instead, since the already-running recording's options can't be changed to turn on heap profiling.

contentTracing.stopRecording([resultFilePath])​

History
  • resultFilePath string (optional)

Returns Promise<string> - resolves with a path to a file that contains the traced data once all child processes have acknowledged the stopRecording request

Stop recording on all processes.

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, Chromium asynchronously asks all child processes to flush any pending trace data.

Trace data will be written into resultFilePath. If resultFilePath is empty or not provided, trace data will be written to a temporary file, and the path will be returned in the promise.

Trace data is written in the Perfetto protobuf format.

Heap profiling samples record instruction addresses and module build IDs rather than function names. To symbolize them, use the symbols published for the matching Electron release with Chromium's symbolize_trace tool.

contentTracing.getTraceBufferUsage()​

History

Returns Promise<Object> - Resolves with an object containing the value and percentage of trace buffer maximum usage

  • value number
  • percentage number

Get the maximum usage across processes of trace buffer as a percentage of the full state.