Raxol.Performance.FlameGraph (Raxol v2.6.0)

Flame graph generation for performance profiling.

Generates flame graphs using Erlang's built-in :fprof profiler and converts output to SVG format compatible with Brendan Gregg's FlameGraph tools.

Usage

# Profile a function and generate flame graph
FlameGraph.profile(fn ->
  expensive_computation()
end)

# Profile with options
FlameGraph.profile(
  fn -> expensive_computation() end,
  output: "my_profile.svg",
  title: "My Operation Profile"
)

# Profile a module for a duration
FlameGraph.profile_module(MyModule, duration: 5000)

Requirements

For SVG generation, one of these must be available:

brendangregg/FlameGraph tools (flamegraph.pl in PATH)
eflambe package (optional dependency)

Without these, raw profiling data is saved in Erlang fprof format.

Summary

Types

profile_opts()

Functions

profile(fun, opts \\ [])

Profiles a function and generates a flame graph.

profile_module(module, opts \\ [])

Profiles all calls to a module for a specified duration.

profile_self(opts \\ [])

Profiles the current process for a duration.

tool_info()

Returns information about available profiling tools.

tools_available?()

Checks if flame graph generation tools are available.

Types

profile_opts()

@type profile_opts() :: [
  output: String.t(),
  title: String.t(),
  width: pos_integer(),
  height: pos_integer(),
  colors: atom(),
  format: :svg | :folded | :fprof
]

Functions

profile(fun, opts \\ [])

@spec profile((-> any()), profile_opts()) ::
  {:ok, String.t(), any()} | {:error, term()}

Profiles a function and generates a flame graph.

Options

:output - Output file path (default: "flamegraph.svg")
:title - Title for the flame graph
:width - SVG width in pixels (default: 1200)
:height - Row height in pixels (default: 16)
:colors - Color scheme (:hot, :mem, :io, :wakeup, :chain)
:format - Output format (:svg, :folded, :fprof)

Examples

FlameGraph.profile(fn ->
  Enum.reduce(1..10_000, 0, &(&1 + &2))
end)

FlameGraph.profile(
  fn -> MyModule.expensive_operation() end,
  output: "profiling/render.svg",
  title: "Render Pipeline"
)

profile_module(module, opts \\ [])

@spec profile_module(
  module(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Profiles all calls to a module for a specified duration.

Options

:duration - How long to profile in milliseconds (default: 5000)
:output - Output file path
:functions - List of specific functions to trace (default: all)

Examples

FlameGraph.profile_module(Raxol.Terminal.Buffer, duration: 3000)

FlameGraph.profile_module(
  Raxol.UI.Components.Input.Button,
  duration: 5000,
  functions: [:render, :handle_event]
)

profile_self(opts \\ [])

@spec profile_self(keyword()) :: {:ok, String.t()} | {:error, term()}

Profiles the current process for a duration.

Examples

# In your GenServer
FlameGraph.profile_self(duration: 3000, output: "server_profile.svg")

tool_info()

@spec tool_info() :: %{
  flamegraph_pl: boolean(),
  eflambe: boolean(),
  fprof: boolean(),
  recommendation: String.t()
}

Returns information about available profiling tools.

tools_available?()

@spec tools_available?() :: boolean()

Checks if flame graph generation tools are available.