flame-graph-d3

What is this?

This is a d3.js plugin that renders flame graphs from hierarchical data.

Flame graphs were invented by Brendan Gregg; you can find the original implementation for drawing them as well as ports to different languages/environments on his website. To quote him:

Flame graphs are a visualization of profiled software, allowing the most frequent code-paths to be identified quickly and accurately. They can be generated using my open source programs on github.com/brendangregg/FlameGraph, which create interactive SVGs. See the Updates section for other implementations.

-- Flame Graphs, Brendan Gregg

Currently implemented features:

• Breadcrumbs - the navbar is populated with the names of the classes that were navigated into.
• Tooltip showing the FQDN of the hovered classes, total and percentual time spent.

Roadmap:

• Filtering from the UI (input with autocomplete)
• Parametrizing the DOM element in which breadcrumbs are rendered
• Zoom by increasing the scale of the SVG
• Code refactoring

How was this made?

This plugin was built using gulp and coffeescript.

API Reference

The methods on the flame graph plugin follow the d3.js conventions on method chaining and accessors.

# d3.flameGraph()

Constructs a new flame graph.

# flameGraph.size([[width, height]])

If [width, height] are specified, sets the svg rendering width and height to the pixel values provided in the array. If [width, height] is not specified, returns the current width. Defaults to [1200, 600].

# flameGraph.margin([{top: , right: , bottom:, left: }]])

If the values are specified, follows the d3 conventions on margins when rendering the chart. If the values are not specified, returns the current margins object. Defaults to { top: 0, right: 0, bottom: 0, left: 0}.

# flameGraph.cellHeight([cellHeight])

If cellHeight is specified, sets the height of the rectangles in the flame graph to the provided value. If cellHeight is not specified, returns the current value. Defaults to 10.

# flameGraph.colors([[colors]])

If colors are specified, it will set the colors available for rendering to the ones passed in as a parameter. If colors are not specified, returns the current available colors. The parameter is expected to be an array of hex color strings. The last value in the array is used for the rectangles' stroke colour. The default colours are 5-class YlOrRd from lib/colorbrewer.

# flameGraph.data([data])

The data the flame graph is rendered from.

TODO: Provide more details on how the data elements are expected to look like.

# flameGraph.render(selector)

Triggers a repaint of the flame graph, using the values previously fed in as parameters. This is the only method that triggers repaint so you need to call it after changing the other parameters to see the changes take effect.

The selector value is required, it defines the DOM element to which the SVG will be appended. Prior to rendering, any svg elements present in the given container will be cleared.

Extras

# flameGraph.breadcrumbs(selector)

If selector is specified, the flame graph will enable clickthrough navigation and will create breadcrumbs in the container referenced by the selector. The breadcrumbs are added as list items, so the container is expected to be an ordered or unordered list. Each breadcrumb reverts the flame graph to a previous state on click. This value needs to be specified for the feature to be enabled, it is disabled by default.

# flameGraph.tooltip(enabled)

If enabled is true, a tooltip will be rendered on top of the cells in the graph on mouseover. The d3-tip plugin is responsible for rendering the tooltip. If set to false, the tooltip is disabled and nothing is rendered on mouseover. The default value is true.

Sample invocation:

d3.flameGraph()
  .size([1200, 600]).cellHeight(10)
  .colors(["#ffffcc","#ffeda0","#fed976","#feb24c","#fd8d3c","#fc4e2a","#e31a1c","#bd0026"])
  .data(profile)
  .breadcrumbs('.breadcrumb')
  .tooltip(true)
  .render('#d3-flame-graph')