├── .gitignore
├── .npmignore
├── Gulpfile.js
├── LICENSE
├── README.md
├── bower.json
├── circle.yml
├── demo
├── data
│ └── profile.json
├── index.html
├── resources
│ ├── favicon.png
│ └── octocat.png
└── src
│ └── demo.coffee
├── flame-graph-screenshot.png
├── package.json
├── scripts
├── deploy-demo.sh
└── release-demo.sh
├── src
├── d3-flame-graph.coffee
└── d3-flame-graph.scss
└── test
├── augment.coffee
├── data
└── profile-test.json
└── hide.coffee
/.gitignore:
--------------------------------------------------------------------------------
1 | demo/data/*.json
2 | build/
3 | dist/
4 | node_modules/
--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | scripts/
2 | build/
3 | demo/
4 | circle.yml
5 | bower.json
6 | flame-graph-screenshot.png
--------------------------------------------------------------------------------
/Gulpfile.js:
--------------------------------------------------------------------------------
1 | var gulp = require('gulp');
2 | var coffee = require('gulp-coffee');
3 | var concat = require('gulp-concat');
4 | var uglify = require('gulp-uglify');
5 | var sass = require('gulp-sass');
6 | var sourcemaps = require('gulp-sourcemaps');
7 | var browserSync = require('browser-sync');
8 | var reload = browserSync.reload;
9 | var del = require('del');
10 |
11 | var paths = {
12 | scripts: ['src/**/*.coffee'],
13 | styles: ['src/**/*.scss'],
14 | demoResources: ['demo/**/*.*', 'dist/**/*.*', '!demo/src/**'],
15 | demoScripts: ['demo/src/**/*.coffee'],
16 | dist: 'dist',
17 | demoOut: 'build'
18 | };
19 |
20 | gulp.task('clean', function(cb) {
21 | del([paths.dist, paths.demoOut], cb);
22 | });
23 |
24 | // Create the distributable artifacts of the plugin.
25 | gulp.task('dist:main', function () {
26 | return gulp.src(paths.scripts)
27 | .pipe(coffee())
28 | .pipe(concat('d3-flame-graph.js'))
29 | .pipe(gulp.dest(paths.dist))
30 | });
31 | gulp.task('dist:min', function () {
32 | return gulp.src(paths.scripts)
33 | .pipe(coffee())
34 | .pipe(uglify())
35 | .pipe(concat('d3-flame-graph.min.js'))
36 | .pipe(gulp.dest(paths.dist));
37 | });
38 | gulp.task('dist:styles', function () {
39 | return gulp.src(paths.styles)
40 | .pipe(sass().on('error', sass.logError))
41 | .pipe(gulp.dest(paths.dist))
42 | });
43 |
44 | gulp.task('dist', ['dist:min', 'dist:main', 'dist:styles']);
45 |
46 | // building the demo page
47 | gulp.task('demo-scripts', ['dist'], function() {
48 | // Minify and copy all JavaScript (except vendor scripts)
49 | // with sourcemaps all the way down
50 | return gulp.src(paths.demoScripts)
51 | .pipe(sourcemaps.init())
52 | .pipe(coffee())
53 | .pipe(concat('demo.js'))
54 | .pipe(sourcemaps.write())
55 | .pipe(gulp.dest(paths.demoOut));
56 | });
57 |
58 | gulp.task('demo-copy', ['demo-scripts'], function() {
59 | return gulp.src(paths.demoResources)
60 | .pipe(gulp.dest(paths.demoOut));
61 | });
62 |
63 | // Rerun the task when a file changes
64 | gulp.task('demo-watch', ['demo-copy'], function() {
65 | gulp.watch(paths.scripts, ['demo-copy']);
66 | gulp.watch(paths.styles, ['demo-copy']);
67 | gulp.watch(paths.demoResources, ['demo-copy']);
68 | gulp.watch(paths.demoScripts, ['demo-copy']);
69 | });
70 |
71 | gulp.task('serve', ['demo-watch'], function() {
72 | browserSync({ server: { baseDir: paths.demoOut } });
73 | gulp.watch(['*.html', '*.css', '*.js'], { cwd: paths.demoOut }, reload);
74 | });
75 |
76 | // The default task (called when you run `gulp` from cli)
77 | gulp.task('default', ['serve']);
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 |
3 | Copyright (c) 2015 Alex Ciminian
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
6 |
7 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8 |
9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | ## What is this?
2 |
3 | This is a d3.js plugin that renders flame graphs from hierarchical data.
4 |
5 | > 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](http://github.com/brendangregg/FlameGraph), which create interactive SVGs. See the Updates section for other implementations.
6 | >
7 | > -- [Flame Graphs](http://www.brendangregg.com/flamegraphs.html), Brendan Gregg
8 |
9 | ## [See the demo!](http://cimi.github.io/d3-flame-graphs/)
10 |
11 | [](http://cimi.github.io/d3-flame-graphs/)
12 |
13 | ## Build status
14 | [](https://circleci.com/gh/cimi/d3-flame-graphs/tree/master) [](https://badge.fury.io/js/d3-flame-graphs) [](https://badge.fury.io/bo/d3-flame-graphs)
15 |
16 | ## Features
17 |
18 | * __Efficient rendering of large profiles__ - large profiles may use up a lot of CPU and memory to render if all samples get represented on the DOM. This plugin only draws samples that would be visible to the user. The performance improvement in the case of very large profiles is in the range of 10x-20x.
19 | * __Zooming__ - on click, the container re-renders the subgraph associated with the clicked node. The previous roots are rendered at the bottom of the graph and are clickable - you can revert to a previous state. An optional callback can be provided if you want to trigger other changes when zooming.
20 | * __Tooltips__ - when hovering over nodes a tooltip can be displayed. The tooltip's contents are parametrizable.
21 | * __Filtering__ - nodes can be selected by name using regex. This enables name-based navigation, highlighting or adding other custom behaviour to certain nodes. See the demo for examples.
22 | * __Hiding across the stack__ - some call paterns only add noise to a graph (like `Object.wait` or `Unsafe.park`, for example). The plugin offers the capability to hide node selections across the stack (their value is subtracted from the parent nodes and their children are hidden). This leads to clearer views of the state of the world.
23 |
24 | ## How was this made?
25 |
26 | This plugin was built using gulp and coffeescript. CircleCI runs tests on every push and manages releasing the demo page and the library to npm and bower. The demo page is hosted on GitHub pages.
27 |
28 | ## API Reference
29 |
30 | The methods on the flame graph plugin follow the [d3.js conventions](http://bost.ocks.org/mike/chart/) on method chaining and accessors.
31 |
32 | # d3.flameGraph(_selector_, _data_)
33 |
34 | Constructs a new flame graph.
35 |
36 | 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.
37 |
38 | The data value is also required, it should be the root of the profile under analysis. There is no need to partition the data prior to feeding in to the plugin as partitioning is done internally. Any operation on the data (zooming, selecting, hiding) will use this value as start of traversal.
39 |
40 | # flameGraph.__size__([_[width, height]_])
41 |
42 | 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]_.
43 |
44 | # flameGraph.__margin__([_{top: , right: , bottom:, left: }]_])
45 |
46 | If the values are specified, follows the [d3 conventions on margins](http://bl.ocks.org/mbostock/3019563) 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}_.
47 |
48 | # flameGraph.__cellHeight__([_cellHeight_])
49 |
50 | 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 20. The graph height should be divisible by the cell height so the nodes align properly.
51 |
52 | # flameGraph.__color__([_[color(d)]_])
53 |
54 | If the _color_ function is specified, it will be used when determining the color for a particular node. The function should expect one parameter, the data element associated with the node. If _color_ is not specified, returns the current function.
55 |
56 | The default function uses a hash of the node's short name to generate the color. The letters are weighted (first letters matter more), the hash only uses the first six characters of the name.
57 |
58 | # flameGraph.__data__([_data_])
59 |
60 | The data the flame graph is rendered from. It expects nested data in the form:
61 |
62 | ```
63 | {
64 | "name": "",
65 | "value": ,
66 | "children": [, , ...]
67 | }
68 | ```
69 |
70 | The data is augmented with 'filler nodes' by the plugin, due to the fact that D3 considers the value of a node to be the sum of its children rather than its explicit value. More details in [this issue](https://github.com/mbostock/d3/pull/574). This should be transparent to clients as the filler node augmentation is done internally. Because of the filler node augmentation, __the children property needs to be defined, even if the array is empty.__
71 |
72 | # flameGraph.__zoomEnabled__(_enabled_)
73 |
74 | If _enabled_ is truthy, zooming will be enabled - clicking a node or calling the zoom method programatically will re-render the graph with that node as root. The default value is _true_.
75 |
76 | # flameGraph.__zoomAction__(_function_)
77 |
78 | If a _function_ is provided, on every zoom - clicking a node or calling the zoom method programatically - the function will be called after the graph is re-rendered. The function receives a data node as its parameter and its return value is ignored.
79 |
80 | # flameGraph.__zoom__(_node_)
81 |
82 | If zoom is enabled, re-renders the graph with the given node as root. The previous roots are drawn at the bottom of the graph, by clicking on it them you can revert back to previous states. Prior to zooming, any svg elements present in the given container will be cleared.
83 |
84 | If zoom is disabled, this method will throw an error.
85 |
86 | [See the demo code](https://github.com/cimi/d3-flame-graphs/blob/master/demo/src/demo.coffee#L69) for an example.
87 |
88 | # flameGraph.__tooltip__(_function_)
89 |
90 | If a _function_ is provided, a tooltip will be shown on mouseover for each cell. Ancestor nodes do not get a tooltip. The function receives a data node as its parameter and needs to return an HTML string that will be rendered inside the tooltip. The d3-tip plugin is responsible for rendering the tooltip. If set to false or not called, the tooltip is disabled and nothing is rendered on mouseover.
91 |
92 | # flameGraph.__select__(_predicate_, [_isDisplayed_])
93 |
94 | Selects the elements from the current dataset which match the given _predicate_ function. If _isDisplayed_ is set to false, it will search all the nodes starting from the root passed to the flame graph constructor and return an array of data nodes. _isDisplayed_ defaults to true, in that case it will only search the currently displayed elements and returns a d3 selection of DOM elements.
95 |
96 | [The demo code contains a usage example](https://github.com/cimi/d3-flame-graphs/blob/master/demo/src/demo.coffee).
97 |
98 | # flameGraph.__hide__(_predicate_, [_unhide_])
99 |
100 | Hides elements that match the given _predicate_ function from the current dataset. The targeted elements and their children are hidden. The value of the target is subtracted from its ancestors so that it's effect is removed across the stack.
101 |
102 | If _unhide_ is set to true, it will perform the reverse operation and re-add the previously subtracted values. _unhide_ defaults to false.
103 |
104 | As this operation needs to traverse the subtree for all matched items, it can potentially be slow on generic queries over large datasets.
105 |
106 | [The demo code contains a usage example](https://github.com/cimi/d3-flame-graphs/blob/master/demo/src/demo.coffee).
107 |
108 | # flameGraph.__render__()
109 |
110 | Triggers a repaint of the flame graph, using the values previously fed in as parameters. This is the only method besides zoom and hide that triggers repaint so you need to call it after changing other parameters like size or cell-height in order to see the changes take effect.
111 |
112 | ### Sample usage:
113 |
114 | The example below is taken from the demo source. Although it is written in CoffeeScript, the plugin can be used from vanilla JS without any issues.
115 |
116 | ```
117 | d3.json "data/profile.json", (err, data) ->
118 | profile = convert(data.profile)
119 | tooltip = (d) -> "#{d.name}