etrace.el - Performance Tracing For Emacs Lisp
This package for GNU Emacs allows latency tracing to be performed on Emacs Lisp code and the results output to files using the Chromium Catapult Trace Event Format. These trace files can then be loaded into trace analysis utilities in order to generate flame graphs and other useful visualisations and analyses. For example, here's a flame graph for (a modified version of) the famous
This package is built on top of
elp.el, which is one of two elisp profiler's built into emacs. (The other is
profiler.el; they are both mentioned in the Profiling section of the Elisp manual.) It records a separate trace using advice on the normal
elp.el recording, since
elp.el doesn't capture enough info itself.
Generating a trace file
M-: (require 'etrace)or add
(require 'etrace)to your Emacs config, or enable the micro-feature for it if you use micro-features from the non-Spacemacs Emacs config.
M-x customize-variable etrace-output-fileto change where the trace will be written. It defaults to
M-x elp-instrument-packageand type in a function prefix to instrument all the functions with that prefix. It uses a completion box so note that by default it will complete to whatever's selected in there. If you want to complete to a prefix with no corresponding function, you may be able to press the Up arrow until the text you typed is selected rather than any completion, although this depends on which completion interface you have configured.
M-x elp-instrument-functionfor individual functions.
Execute the code which you want to analyse.
M-x etrace-writeto write out the trace file.
Analysing the trace file
There are several tools which can analyse the resulting trace file. Here are some suggestions, but if you know of other good alternatives, please submit them to this repository.
This is an excellent Open Source interactive web-based flamegraph visualizer, which has 3 visualisation modes, keyboard shortcuts, lots of nice features, and good documentation. Simply upload your trace file and then start analysing.
This tool can show you the total time and percentage of time taken by different functions in a selection range.
If you are using Chromium, Google Chrome, or a similar derivative, open this built-in tracing tool, and click the load button to open the trace file. Use Alt+scroll to zoom.
If you successfully identify performance bottlenecks and fix them then repeat from step 4, or from step 3 if any code needs to be re-instrumented.
Finally, you can run
M-x elp-restore-all to un-instrument any instrumented functions.