{"id":24742299,"url":"https://github.com/orenbenkiki/flameview","last_synced_at":"2025-03-22T20:43:06.520Z","repository":{"id":66748467,"uuid":"155388958","full_name":"orenbenkiki/flameview","owner":"orenbenkiki","description":"Generate a flame graph view.","archived":false,"fork":false,"pushed_at":"2018-11-30T08:51:56.000Z","size":159,"stargazers_count":15,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-28T00:38:14.142Z","etag":null,"topics":["flamegraph"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orenbenkiki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-30T13:21:18.000Z","updated_at":"2024-03-12T01:24:09.000Z","dependencies_parsed_at":"2023-09-09T12:36:04.901Z","dependency_job_id":null,"html_url":"https://github.com/orenbenkiki/flameview","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenbenkiki%2Fflameview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenbenkiki%2Fflameview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenbenkiki%2Fflameview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orenbenkiki%2Fflameview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orenbenkiki","download_url":"https://codeload.github.com/orenbenkiki/flameview/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245020314,"owners_count":20548156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flamegraph"],"created_at":"2025-01-28T00:33:35.271Z","updated_at":"2025-03-22T20:43:06.499Z","avatar_url":"https://github.com/orenbenkiki.png","language":"HTML","readme":"# flameview\nGenerate a flame graph view.\n\n## REQUIREMENTS\n\n`flameview.py` requires Python 3.6 or above. It does not require the installation\nof any supporting modules.\n\n## INSTALLATION\n\nDownload\n[flameview.py](https://raw.githubusercontent.com/orenbenkiki/flameview/master/flameview.py)\nand place it in your path. You might need to tweak the `#!` line to execute the\ncorrect python interpreter; by default it invokes `python3`.\n\n## STATUS\n\nThis is a beta version **0.1-b6**. It provides the basic functionality and seems\nto work in Firefox, Chrome and Edge. However, it hasn't been heavily tested.\nFeedback is welcome.\n\n## EXAMPLES\n\nThe\n[example.fg](https://github.com/orenbenkiki/flameview/blob/master/example.fg)\nwas copied from one of the example files in ``flamegraph.pl``. The generated HTML\n(using the command line `flameview.py example.fg \u003e example.html`), is in\n[example.fg.html](https://htmlpreview.github.io/?https://github.com/orenbenkiki/flameview/blob/master/example.fg.html).\n\nHover over any cell to view its data in a tooltip. Alt-click to toggle the\ntooltips. If you hover over the ``collections::vec::from_elem::...`` cell, you\nwill see it takes 21.62% of the samples. You will notice that additional cells\nare highlighted. If you control-click any of them, you will see the same\nfunction is invoked in three different call chains. Hover over the bottom \"all\"\ncell to see these take 32.43% of the total samples. Click the bottom \"all\"\ncell to return to viewing the full graph.\n\nThe [example.fg](https://github.com/orenbenkiki/flameview/blob/master/example.fv) was generated\nespecially for use by ``flameview.py``, that is, it makes use of its additional features. It was\ncaptured from an execution of a bio-informatics pipeline. The execution is parallelized across\nmultiple processes. Each spawn point is marked with a \"-\" cell (appears in gray). If you\ncontrol-click on any \"(sync)\" cell, and then hover over the bottom \"all\" cell, you will see the\ntotal overhead of synchronization between these processes is 8.98%. The cell tooltips contain the\nnumber of invocations. Cells in parallel processes show the average measurements in each process,\nand their tooltip also list the number of processes used.\n\n## USAGE\n\nThe output of ``flameview.py -h`` is:\n\n    usage: flameview.py [-h] [--minpercent PERCENT] [--sortby SORT_KEY]\n                        [--inverted] [--title TITLE] [--sizename NAME]\n                        [--nodefaultcss] [--addcss CSS] [--colors PALETTE]\n                        [--seed SEED] [--strict] [--output HTML] [--version]\n                        [FLAMEGRAPH]\n\n    Generate a flamegraph view.\n\n    positional arguments:\n      FLAMEGRAPH            The flamegraph data file to read; default: \"-\", read\n                            from standard input\n\n    optional arguments:\n      -h, --help            show this help message and exit\n      --minpercent PERCENT  The minimal percent of the entries to display;\n                            default: 0.1 (1/1000 of the total)\n      --sortby SORT_KEY     How to sort nodes: name (default) - lexicographically,\n                            size - by the size data, input - by input order\n      --inverted            If specified, generate an inverted (icicles) graph.\n      --title TITLE         An optional title for the HTML document; default:\n                            \"Flame Graph\" or \"Icicle Graph\"\n      --sizename NAME       The name of the size data; default: \"samples\".\n      --nodefaultcss        If specified, the default appearance CSS is omitted,\n                            probably to avoid interfering with --addcss\n      --addcss CSS          The name of a CSS file to embed into the output HTML\n      --colors PALETTE      The color palette to use, subset of flamegraph.pl;\n                            default: \"hot\", other choices: mem, io, red, green,\n                            blue, aqua, yellow, purple, orange\n      --seed SEED           An optional seed for repeatable random color\n                            generation; default: None\n      --strict              If specified, abort with an error on invalid input\n                            lines.\n      --output HTML         The HTML file to write; default: \"-\", write to\n                            standard output\n      --version             Print the version information (0.1-b6) and exit\n\n    INPUT: A flamegraph file. Each line must be in the format:\n\n        name;...;name size [difference] [#tooltip_html]\n\n    OUTPUT: An HTML file visualizing the flame graph.\n\n## DESCRIPTION\n\n`flameview.py` is inspired by the `flamegraph.pl` program, which you can obtain\nfrom https://github.com/brendangregg/FlameGraph. The `flamegraph` program is\nmuch more mature, contains a detailed description of what flame graphs are, and\nprovides many features that `flameview` lacks: support for differential graphs,\nflamecharts, stable hash-based colors, automatic language-specific color\npalettes, ...\n\nThe `flameview` program does provide some features that `flamegraph` lacks:\n\n* Each input line may end with a `#` character followed by an arbitrary HTML\n  string. This string will be placed in the tooltip displayed when hovering\n  above the relevant graph cell. This allows attaching arbitrary data to each\n  cell. For example, it is possible to display both CPU time (as the sizes) and\n  invocations count (in the tooltip), similarly to the output of `gprof`.\n\n* Size data may be float rather than only integer. This allows, for example,\n  to directly use wall clock time, in seconds, as the size measure.\n\n* Size data is optional. This allows attaching tooltip information to cells\n  that don't have direct measurements (but have sub-cells that do).\n\n* The output is an interactive file, using HTML rather than SVG. As a result,\n  there is no need to specify the size of the graph in advance. Instead it\n  always spans the full width of the browser's window.\n\n* Selecting (clicking on) a cell restricts the view to the subset of the graph\n  rooted in the selected cell. Selecting the bottom \"all\" cell views all the\n  graph.\n\n  Control-clicking a cell allows for de/selecting multiple cells. The currently\n  selected cell(s) are highlighted. There is always at least one such selected\n  cell; by default it is the bottom \"all\" cell.\n\n  When more than one cell is selected, the lowest-level one restricts the view\n  to the subset of the graph rooted in that cell, as usual. The additional\n  selected higher-level cells further restrict the view, to include only paths\n  that contain any cell with the same name as these higher-level selected cells.\n\n* Hovering over any cell highlights all other cells with the same name. These\n  are the cells that will remain visible if you add the cell to the selection\n  using control-click.\n\n  Hovering over any cell will display a tooltip containing its name, its size,\n  the percentage of this size out of the total and visible graph, and the\n  additional tooltip HTML, if any, from the input file. Since tooltips are\n  intrusive alt-clicking on a tooltip or a cell toggles them.\n\n  Hovering over the \"all\" cell when a subset of the graph is visible will\n  display a tooltip with the percentages of the currently visible (selected)\n  graph out of the total graph.\n\n* Explicit \"(self)\" cells are created when some call chain has both its own\n  size and also sizes for further nested call chains. In such a case, the self\n  cell will display the input tooltip and the sizes for the call chain; the\n  lower level cell will display the sum of the self size and all the nested\n  invocations.\n\nThe above allows the result flame graph to provide all the information one would\nget from a `gprof` output (and more), in a visual form:\n\n* The tooltips may provide the invocations count, or any other data which is\n  associated with the call chain.\n\n* Self nodes allow viewing the sizes of the function itself, as opposed to the\n  sum of the function and everything it invokes (which is also available).\n\n* If \"all\" is selected, and you control-click to select a function \"foo\", you\n  will see all the invocations of the \"foo\" function anywhere in the graph, each\n  one above its caller chain. This makes it easy to see the both total measure\n  of \"foo\", what percentage this is of the program's total, and which percentage\n  is due to which caller.\n\n* A further control-click of a higher level \"bar\" function will show all the\n  invocations of \"bar\" from \"foo\". This makes it easy to see which percentage of\n  the sizes is due to any \"bar\" invoked from \"foo\" (directly or indirectly).\n\n* A further control-click to deselect \"all\" will restrict the view to only the\n  calls to \"bar\" from the specific selected invocation of \"foo\", again allowing\n  to view the total size and percentages of such calls.\n\nThat is, by selecting multiple cells it is possible to gain valuable additional\ninsights about the execution, which are impossible to obtain using the output of\n`flamegraph.pl`, even though the data is present in the graph.\n\nTWEAKING\n--------\n\nThe output of `flameview` tries to be well-behaved CSS-annotated HTML 5 (clean\naccording to https://validator.w3.org/), with the inevitable embedded javascript\ncode (clean according to https://jslint.com/ except for containing long\ngenerated data lines). The file requires no external resources, and contains\nhopefully helpful comments to help tweaking it.\n\nThe HTML uses absolute positioning to control the horizontal location of the cells,\nand lets HTML automatically determine the height of each row (one \"normal\"\ntext line height). I tried using both `table` and CSS ``grid`` layout but\nneither approach gave me the needed control across browsers.\n\nIt should be \"easy\" to tweak the appearance of the graph by tweaking the CSS.\nThe embedded CSS stylesheet is given in two parts. The first part controls the\nlayout, which you probably don't want to mess with (unless you want to try\nswitching to CSS grid layout).\n\nThe second part controls appearance, using the following CSS selectors:\n\n* `#graph`: The `div` containing the whole graph.\n\n* `.tooltipped`: Class applied to `graph` when tooltips are enabled. This gets\n  removed when alt-clicking on any tooltip, disabling tooltips. It is restored\n  when alt-clicking on any cell, re-enabling the tooltips.\n\n* `#width`: An empty `div` following the graph, used to detect the available\n  vertical space. If you force its width, the graph will adjust accordingly.\n\n* `.row`: Class for a `div` containing a single graph row. Uses relative\n  positioning.\n\n* `.height`: An invisible `div` containing `\u0026nbsp;` to force the height of the\n  row. If you adjust its height, the row will adjust accordingly. Note the\n  actual row cells do not affect the height because they use absolute\n  positioning.\n\n* `.self`, `.leaf`, `.sum`: Classes for `div` elements, reflecting the kind of\n  cell. Currently simple border/centering rules are applied to all cells.\n\n  The background color of cells is hard-coded in the `div` element according to\n  the chosen color palette. It might arguably make sense to define some color\n  classes instead, and switch palettes using CSS instead.\n\n* `.tooltip`: Class for the `div` contained in each cell to hold the tooltip.\n  This uses absolute positioning and is only visible when hovering over the\n  cell, and tooltips are enabled.\n\n* `.name`: Class for a `span` inside the tooltip `div`, which holds the name of\n  the cell. Note the name may be different from the label; specifically, when\n  the label is \"(self)\", the name is \"name;(self)\". Currently the CSS just makes\n  the name font *italic*.\n\n* `.basic`: Class for a `div` inside the tooltip, which holds the basic computed\n  data about the cell. Currently this has no special formatting.\n\n* `.computed`: Class for an empty `span` inside the basic `div`, which is\n  automatically filled with the computed size sum and percentage depending on\n  the visible cells. Currently this has no special formatting.\n\n* `.extra`: Class for a `div` inside the tooltip, which holds the extra tooltip\n  HTML from the input file. Currently this has no special formatting.\n\n* `.label`: Class for the `div` contained in each cell to hold the label. Making\n  this a sibling rather than a parent of the tooltip makes it easier to apply\n  CSS rules only to it.\n\n* `.group_hover`: Class applied to each cell that has the same name as the one\n  under the mouse. Currently this turns the cell(s) background color to `ivory`,\n  which makes them stand out of the rest of the colored cells.\n\n* `.selected`: Class for the currently selected cell(s). Currently this just\n  makes the label font **bold**. This might be too subtle an effect.\n\nYou can append additional CSS rules into the HTML to tweak the default\nappearance CSS, or omit the default and provide a full replacement CSS\ninstead.\n\nFURTHER WORK\n------------\n\n* If HTML is preferable to SVG, then it would make sense to further develop\n  `flameview.py` to become a true replacement for `flamegraph.pl`. This would\n  require re-implementing all the features already present in `flamegraph`. None\n  of the features seem terribly complex, but their total is far from trivial.\n\n  Otherwise, it might make more sense to enhance the SVG output of\n  `flamegraph.pl` to provide for multiple cell selection and explicit \"(self)\"\n  nodes. This would have to be done in Perl though ;-)\n\n* The default CSS appearance rules could definitely be improved. It is also\n  technically trivial to provide a selection between several built-in\n  `--csstheme` options. Actually designing such options is much more work.\n\n* Using absolute positioning for layout is basically giving up on the CSS layout\n  engine. It would be nice if CSS grid layout could be made to handle this for\n  us instead.\n\nThe code is pretty simple and short (~1K LOC total, including the Python, CSS,\nJavascript and HTML). It gets a clean bill of health from `mypy` and `pylint`.\nPull requests are welcome.\n\n## LICENSE\n\n`flameview.py` is available under the MIT license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forenbenkiki%2Fflameview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forenbenkiki%2Fflameview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forenbenkiki%2Fflameview/lists"}