image::doc/eflambe-torch-logo.png[E flambè, a tool for rapid profiling of Erlang and Elixir applications]

* Designed for rapid generation of flamegraphs - no need to edit source code or recompile!
* Generates output in several common formats - perf and Brendan Gregg's
* Interface inspired by recon_trace to automatically stop flamegraph generation
* Can automatically open data your flamegraph viewer of choice

== Example Output

<insert screenshot of speedscope>

== Description

This tool is designed to be the first profiling tool you reach for during development. It is designed for rapid visualization of program execution. It generates one or more flamegraphs of any function you specify. You can easily select function(s) to profile in the shell without having to alter your code or restart your application. This tool has two distinct advantages over existing flamegraph generators in Erlang:

* It doesn't require the user to insert profiling code into the functions they want to visualize as flamegraphs. Everything can be done on the fly without restarting your application.
* It generates output in formats used by most flamegraph viewers. No manual post-processing is needed.
* No Perl code.

== Installation

=== Elixir

Add the following line to your `mix.exs` file:

[source, elixir]

=== Erlang

Add the following line to your `rebar.config` file:

[source, elixir]

== Usage

* `eflambe:apply/1,2,3`

* `eflambe:capture/1,2,3`

=== Options

* `{output_directory, Dir}` - Specify the output directory to write trace data to. Default is project root.
* `{output_format, Format}` - Specify the output format. `Format` must be one of `perf` or `brendan_gregg`. Default is `perf`.
* `{open, Program}` - Specify the program to load the trace output in after output is generated. `Program` must be one of `speedscope` or `hotspot`. By default this option is not set

=== Interactive Use

=== Manually placing start/stop calls

=== Output Formats

== Example Outputs

== Implementation

While designing this tool there were several different approaches I considered. Because I wanted the user to be able to dynamically select functions to profile at runtime, I'd need to start tracing any process that invoked the selected function. Unfortunately it's hard to turn tracing on at an exact point in time for a specific process. All the existing tracing libraries do not support this. An ideal implementation would have been an `erl_tracer` behavior that blocked execution when the selected function was invoked for just long enough to start a trace of all the internal function calls. But unfortunately this wasn't possible due to the fact that `erl_tracer` callbacks must be NIFs and NIFs cannot call Erlang functions directly. There are some hacky ways to get around this, but it didn't feel like a good solution.

The solution I settled on is unfortunately no less hacky but is a bit more straightforward. Instead of trying to halt execution at a specific point in time, we use meck to create a mock of the module containing the function the user wants to profile with the passthrough option enabled. This results in a new module that is an exact copy, but it allows us to override wrap the function the user specified for profiling in eflambe profiling code. Once profiling is complete the mock is removed and the original module is restored. The downside to this is that we've injected code into the module the user wants profiled, so the data collected doesn't provide an accurate picture of the performance of the function itself. It should however provide a fairly accurate picture of the performance of all the code inside the function.

Heavily inspired by:


== Contributing

Feedback is welcome! This was started as a hackathon project but I plan on maintaining it for my teams every day use, so if you see something that could be improved please open an issue!