stackcollapse-ghc
Program to fold GHC prof files into flamegraph input
https://github.com/marcin-rzeznicki/stackcollapse-ghc
Version on this page: | 0.0.1.3 |
LTS Haskell 19.33: | 0.0.1.4@rev:1 |
Stackage Nightly 2022-03-17: | 0.0.1.4@rev:1 |
Latest on Hackage: | 0.0.1.4@rev:1 |
stackcollapse-ghc-0.0.1.3@sha256:c095e96503a577fe445b518758dfad96c85fd912f7b638f8b5c77554de6866f9,5346
Module documentation for 0.0.1.3
There are no documented modules for this package.
stackcollapse-ghc
Program to fold GHC prof files into flamegraph input
Motivation
The reasons why this package exists despite other packages with similar functionality (not including the NIH syndrome) boil down to:
- it does only one thing (stack collapsing), so it’s up to the user to install flamegraph scripts, pass options etc (in my eyes it’s not a limitation, on the contrary),
- output control: annotations (color profiles), extending traces from a configured set of modules with the source locations or toggling qualified names,
- precise ticks and/or bytes with
-p
reports, - it’s fast
Table of Contents
Basic usage
(all the following examples assume you have installed flamegraph
on your path)
Visualize ticks
If you have a detailed prof file (-P
RTS option)
stackcollapse-ghc prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks > path_to_svg
If you have a standard prof file (-p
RTS option)
stackcollapse-ghc -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks > path_to_svg
Visualize allocations
If you have a detailed prof file (-P
RTS option)
stackcollapse-ghc --alloc prof_file | flamegraph.pl --title 'Example' --subtitle 'Bytes allocated' --countname bytes > path_to_svg
If you have a standard prof file (-p
RTS option)
stackcollapse-ghc --alloc -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Bytes allocated' --countname bytes > path_to_svg
Cookbook
Using distinct colors for modules
Works out of the box. You just need to tell the program which modules are “yours” (by default it only assumes Main
) and pass the desired color scheme to the flamegraph script
stackcollapse-ghc -u Example prof_file | flamegraph.pl --title 'Example with colors' --subtitle 'Time' --countname ticks --color java > path_to_svg
(the traces coming from your modules are green under this palette)
Or you can use the mem
pallette to track allocations
stackcollapse-ghc -u Example --alloc -p prof_file | flamegraph.pl --title 'Example with colors' --subtitle 'Bytes allocated' --countname bytes --color mem > path_to_svg
This is achieved by using a thing called annotations. stackcollapse-ghc
adds the annotation _[j]
to traces from modules in -u
, _[i]
to CAFs and _[k]
to the “kernel” modules, such as GHC
or System
Turning off qualified names
You might want to tone down the visual clutter in your flamegraph by turning off the qualified names for some modules. You can use the -u
option for this just as in the color pallete examples. Traces from the modules that you have passed in -u
will have unqualified names by default
stackcollapse-ghc -u Example -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks > path_to_svg
If you want to use visual indications and retain qualified names you can use the following option
stackcollapse-ghc -Q -u Example -p prof_file | flamegraph.pl --title 'Example' --subtitle 'Time' --countname ticks --color java > path_to_svg
Adding source locations
If you want to see the source of the traces on the generated flamegraph, you can do it selectively by combining -u
options to mark the modules for which you want to include locations, with -s
stackcollapse-ghc -s -u Example prof_file | flamegraph.pl --title 'Example with sources' --subtitle 'Time' --countname ticks > path_to_svg
Alternatively, you can simply include it for all traces (with or without -u
depending on whether you need it for something else, such as colors or qualified names)
stackcollapse-ghc -S prof_file | flamegraph.pl --title 'Example with sources' --subtitle 'Time' --countname ticks > path_to_svg
All options
Usage: stackcollapse-ghc [OPTIONS] FILE
OPTIONS:
-P Process detailed prof file ('-P' or '-pa' options) (default)
-p Process standard prof file ('-p' option)
-u module_name --user-module=module_name Name of an user module (may be repeated to add more than one). Matches the whole "hierarchy", so `MyModule` matches `MyModule` as well as `MyModule.Internal`
-t --time Collapse with respect to time (default)
-a --alloc Collapse with respect to allocations
-S Append source location to every function name
-s Append source location to functions defined in user modules
--no-source Do not append source location (default)
-Q Always use qualified functon names
--no-qualified Do not use qualified function names
-q Use qualified names for functions not defined in user modules (default)
-A --annotations, --annot Add annotations to output (j - user modules, k - GHC and System, i - CAFs)
--no-annotations, --no-annot Do not add annotations to output
Installation
You can install it from Hackage or Stackage by using either cabal
:
cabal v2-update
cabal v2-install stackcollapse-ghc
or stack
stack install stackcollapse-ghc
Changes
Changelog
stackcollapse-ghc
uses PVP Versioning.
The changelog is available on GitHub.
0.0.1.3
This release does not change functionality
- Rebuild with recursion-schemes >=5.2 && < 5.3
0.0.1.2
This release does not change functionality
- Rebuild with hspec-golden ==0.1.0.2 and fix
Missing field in record construction failFirstTime
(test suite)
0.0.1.1
- Report line location for all errors.
- Allow build with foldl > 1.4.6
0.0.1
- Initially created.