RTS Callstack annotation library.

ghc-stack-annotations

A compatibility library for the RTS callstack annotations introduced in GHC 9.14.

handleGetRequest :: Int -> IO Int
handleGetRequest number = annotateStackStringIO "My User Annotation" $ do
    bigOperationThatCouldFail number

The annotation primop called by handleGetRequest pushes a stack frame which contains a user-annotation. The stack decoding logic can interpret these frames and display the user-annotated information during exceptions and sample profiling.

• Better Haskell stack traces via user annotations

Since the annotation primop has only been introduced in GHC-9.14, the annotation functions do not do anything if used on earlier GHC versions.

IPE backtraces which include annotation stack frames offers a number of advantages over the existing backtrace collection mechanisms:

• It is not necessary to modify the function API (unlike HasCallStack)
• A "continuous chain" of modifications is not necessary (unlike HasCallStack)
• The annotations work in all ways of compilation (unlike cost centre stacks)
• The backtrace is expressed in terms of predictable source locations (unlike some IPE backtraces)

Further, tools such as ghc-stack-profiler can also use the annotation stack frame to provide improved profiles.