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

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

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:

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]

Properties

Versions 0.0.1, 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.14), bytestring (>=0.10.8), containers (>=0.6.0.1), extra, foldl (==1.4.6), recursion-schemes (==5.1.3), rosezipper (==0.2), safe (>=0.3 && <0.4), text (>=1.2.3.0), transformers (>=0.5.6 && <0.5.7) [details]
License GPL-3.0-only
Copyright 2020 Marcin Rzeźnicki
Author Marcin Rzeźnicki
Maintainer Marcin Rzeźnicki <marcin.rzeznicki@gmail.com>
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 2020-05-25T01:08:03Z

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for stackcollapse-ghc-0.0.1

[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:

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

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