Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aspiers/etrace

Emacs Lisp Latency Tracing for the Chromium Catapult Trace Event Format
https://github.com/aspiers/etrace

emacs emacs-lisp performance profiling tracing

Last synced: 10 days ago
JSON representation

Emacs Lisp Latency Tracing for the Chromium Catapult Trace Event Format

Host: GitHub
URL: https://github.com/aspiers/etrace
Owner: aspiers
License: mit
Created: 2020-10-24T21:11:14.000Z (over 4 years ago)
Default Branch: master
Last Pushed: 2020-10-25T13:38:22.000Z (over 4 years ago)
Last Synced: 2025-01-19T16:10:27.420Z (14 days ago)
Topics: emacs, emacs-lisp, performance, profiling, tracing
Language: Emacs Lisp
Homepage:
Size: 8.79 KB
Stars: 73
Watchers: 6
Forks: 1
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # `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 `org-agenda` function:

![image](https://user-images.githubusercontent.com/100738/96385726-9e5eb580-118d-11eb-8ded-569cf8faf9b4.png)

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](https://www.gnu.org/software/emacs/manual/html_node/elisp/Profiling.html).)

It records a separate trace using advice on the normal `elp.el`

recording, since `elp.el` doesn't capture enough info itself.

## Usage

### Generating a trace file

1.  Either `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.

2.  (Optional) Run `M-x customize-variable etrace-output-file` to

    change where the trace will be written.  It defaults to `~/etrace.json`.

3.  Run `M-x elp-instrument-package` and 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.

    There's also `M-x elp-instrument-function` for individual

    functions.

4.  Run `M-x etrace-clear`.

5.  Execute the code which you want to analyse.

6.  Run `M-x etrace-write` to 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.

*   https://www.speedscope.app/

    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.

*   https://ui.perfetto.dev/

    This tool can show you the total time and percentage of time taken

    by different functions in a selection range.

*  [chrome://tracing](chrome://tracing)

    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.

## History and acknowledgements

This package was originally written by [Tristan

Hume](https://github.com/trishume) and shared as [a GitHub

gist](https://gist.github.com/trishume/40bf7045a23412d4c016f5e8533437db).

However he didn't have plans to develop it further, so he generously

[handed over

maintenance](https://gist.github.com/trishume/40bf7045a23412d4c016f5e8533437db#gistcomment-3495349).