# Incendium

Add [flamegraphs](http://www.brendangregg.com/flamegraphs.html) to your Benchee benchmarks.

## Example flamegraph

<link rel="stylesheet" href="doc_extra/assets/incendium.css" />
<script src="doc_extra/assets/incendium.js" charset="utf-8"></script>

<script type="text/javascript" src="doc_extra/assets/incendium_flamegraph_hkctthqlqhcubcsgrazymmvaldzllxbq.js"></script>

## Installation

The package can be installed
by adding `incendium` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:incendium, "~> x.y.z"}
  ]
end
```

Documentation can be found at [https://hexdocs.pm/incendium](https://hexdocs.pm/incendium).

<!-- ex_doc -->
## Rationale

Profiling Elixir code is easy using the default Erlang tools, such as `fprof`.
These tools produce a lot of potentially useful data, but visualizing and interpreting all that data is not easy.
The erlang tool [`eflame`](https://github.com/proger/eflame) contains some utilities to generate flamegraphs from the results of profiling your code

But... `eflame` expects you to manually run a bash script, which according to my reading seems to call a perl (!) script that generates an interactive SVG.
And although the generated SVGs support some minimal interaction, it's possible to do better.

Incendium can be used to run benchmarks with integrated profiling data (in the form of flamegraphs).
It uses [Benchee]() under the hood, and the API is actually quite similar to Benchee's.

It provides a single function, namely `Incendium.run/2`, which takes the same arguments as `Benchee.run/2`, plus some incendium-specific ones. The main difference is that the suite title is a required keyword argument instead of an optional one.

An example:

```elixir
defmodule Incendium.Benchmarks.Example do
  defp map_fun(i) do
    [i, i * i]
  end

  def run() do
    list = Enum.to_list(1..10_000)

    Incendium.run(%{
      "flat_map" => fn -> Enum.flat_map(list, &map_fun/1) end,
      "map.flatten" => fn -> list |> Enum.map(&map_fun/1) |> List.flatten() end
      },
      title: "Example",
      incendium_flamegraph_widths_to_scale: true
    )
  end
end

Incendium.Benchmarks.Example.run()
```

The output of the script above can be found [here](https://hexdocs.pm/incendium/0.4.0/assets/Example.html).