# `ghc-stack-annotations`

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

```haskell
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](https://www.well-typed.com/blog/2025/09/better-haskell-stack-traces/)

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`](https://github.com/well-typed/ghc-stack-profiler) can also use the annotation stack frame
to provide improved profiles.