ghc-stack-profiler: RTS Callstack profiler for GHC.

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:

[missing-upper-bounds] On library, these packages miss upper bounds: - ghc-prim Please add them. There is more information at https://pvp.haskell.org/

RTS Callstack profiler for GHC.

The main idea is to periodically sample the Haskell callstack and use IPE and stack annotation information in order to understand the source locations which correspond to the stack frames. To profile a program it needs to be compiled and instrumented with the 'ghc-stack-profiler' package via:

import GHC.Stack.Profiler.Sampler

main :: IO ()
main = withStackProfilerForMyThread (SampleIntervalMs 10) $ do
    ...

This will spawn a profiling thread that will periodically take a snapshot of the current RTS callstack of your program and serialises it to the eventlog.

To improve readability of the profile, compile the program with -finfo-table-map and -fdistinct-constructor-tables. Using cabal, this can be achieved with an appropriate cabal.project file:

packages: ...

...

package *
    ghc-options: -finfo-table-map -fdistinct-constructor-tables

To emit the eventlog messages by the profiler, you need to run your program with the -l RTS flag, for example via:

./<program> ... +RTS -l -RTS

This will write out an eventlog to <program>.eventlog which can be transformed for speedscope.app via the script 'ghc-stack-profiler-speedscope'.

ghc-stack-profiler-speedscope <program>.eventlog

The resulting profile <program>.eventlog.json can be viewed and further analysed in speedscope.app.

Note that the results are affected by compilation optimisation options, such as -fno-omit-yields.

Properties

Versions	0.1.0.0, 0.1.0.0
Change log	CHANGELOG.md
Dependencies	base (>=4.20 && <4.23), binary (>=0.8.9.3 && <0.11), bytestring (>=0.12.2 && <0.13), ghc-experimental (>=9.1400 && <9.1600), ghc-heap (>=9.10.1 && <9.16), ghc-internal (>=9.1001 && <9.1600), ghc-stack-profiler-core (>=0.1 && <0.2), ghc-trace-events (>=0.1.2.10 && <0.2), text (>=2 && <2.2) [details]
License	BSD-3-Clause
Author	Hannes Siebenhandl, Wen Kokke, Matthew Pickering
Maintainer	hannes@well-typed.com
Category	Profiling, Benchmarking, Development
Uploaded	by fendor at 2025-12-09T12:59:43Z

Modules

Debug
- Trace
  - Binary
    - Debug.Trace.Binary.Compat
GHC
- Internal
  - ClosureTypes
    - GHC.Internal.ClosureTypes.Compat
  - Heap
    - Closures
      - GHC.Internal.Heap.Closures.Compat
  - InfoProv
    - Types
      - GHC.Internal.InfoProv.Types.Compat
  - Stack
    - Constants
      - GHC.Internal.Stack.Constants.Compat
    - Decode
      - GHC.Internal.Stack.Decode.Compat
- Stack
  - Annotation
    - Experimental
      - GHC.Stack.Annotation.Experimental.Compat
  - Profiler
    - GHC.Stack.Profiler.Decode
    - GHC.Stack.Profiler.Sampler
    - Stack
      - GHC.Stack.Profiler.Stack.Compat
      - GHC.Stack.Profiler.Stack.Decode
    - GHC.Stack.Profiler.Util

Flags

Manual Flags

Name	Description	Default
use-ghc-trace-events	Use the package 'ghc-trace-events'	Enabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

ghc-stack-profiler-0.1.0.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

fendor

For package maintainers and hackage trustees

edit package information