stackcollapse-ghc: Program to fold GHC prof files into flamegraph input

[ gpl, profiling, program ] [ Propose Tags ] [ Report a vulnerability ]

Program to fold GHC prof files into flamegraph input 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

Basic usage

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

See the full README for details.


[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.0.1, 0.0.1.1, 0.0.1.2, 0.0.1.3, 0.0.1.4
Change log CHANGELOG.md
Dependencies base (>=4.12.0.0 && <4.16), bytestring (>=0.10.8), containers (>=0.6.0.1), extra, foldl (>=1.4.6 && <1.5), recursion-schemes (>=5.2 && <5.3), rosezipper (==0.2), safe (>=0.3 && <0.4), text (>=1.2.3.0), transformers (>=0.5.6 && <0.5.7) [details]
Tested with ghc ==8.6.5, ghc ==8.8.2, ghc ==8.8.3, ghc ==8.10.1, ghc ==8.10.2, ghc ==8.10.3, ghc ==9.0.1
License GPL-3.0-only
Copyright 2020-2021 Marcin Rzeźnicki
Author Marcin Rzeźnicki
Maintainer Marcin Rzeźnicki <marcin.rzeznicki@gmail.com>
Revised Revision 1 made by rzeznik at 2021-10-10T19:51:49Z
Category Profiling
Home page https://github.com/marcin-rzeznicki/stackcollapse-ghc
Bug tracker https://github.com/marcin-rzeznicki/stackcollapse-ghc/issues
Source repo head: git clone https://github.com/marcin-rzeznicki/stackcollapse-ghc.git
Uploaded by rzeznik at 2021-05-10T01:35:12Z
Distributions
Executables stackcollapse-ghc
Downloads 1023 total (5 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs not available [build log]
Last success reported on 2021-05-10 [all 3 reports]

Readme for stackcollapse-ghc-0.0.1.4

[back to package description]

stackcollapse-ghc

Build status Hackage Stackage Lts Stackage Nightly GPL-3.0-only license

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

Ticks

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

Bytes

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)

JavaColor

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

MemColor

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

UserModules

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

UserSources

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

AllSources

"Reverse" flamegraphs

Sometimes it makes sense to to have functions at the bottom and their callers above them. This mode is called "reverse" flamegraph. You can make such graphs with stackcollapse-ghc (the real work is done by the flamegraph script)

stackcollapse-ghc prof_file | flamegraph.pl --reverse --title 'Reverse' --countname ticks > path_to_svg

Reverse

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