# `opentelemetry-plugin` - a GHC plugin for open telemetry

This GHC plugin lets you export granular open telemetry metrics for your Haskell
builds.  Specifically, this creates a trace with:

- One span for each module build
- One sub-span for each phase of each module build

![Example trace generated by this GHC plugin](https://user-images.githubusercontent.com/1313787/272098736-1d1e4e7b-4122-45be-8f7b-e74f2ccddab0.png)

Note that due to limitations of GHC's `Plugin` interface the root span generated
by this plugin will have a duration of 0 (by default) and will not be the
correct duration (for the entire build).  However, the `Plugin` will reuse any
surrounding span inherited via
[the standard `TRACEPARENT` and `TRACESTATE` environment variables](https://www.w3.org/TR/trace-context/),
so if you wrap your build in something like the `hotel` executable (from
[the `hotel-california` package](https://github.com/parsonsmatt/hotel-california))
then you will get the correct duration for the outermost span.

This plugin also supports
[the standard `BAGGAGE` environment variable](https://www.w3.org/TR/baggage/),
too.

To use this plugin:

- add the `opentelemetry-plugin` package as a build dependency of your package

- add `ghc-options: -fplugin OpenTelemetry.Plugin` to your package

- configure the appropriate open telemetry environment variables

  In other words, you'll probably want to set at least
  `OTEL_EXPORTER_OTLP_ENDPOINT` and maybe other environment variables depending
  on your open telemetry backend.  For example, if you're using
  [Honeycomb](https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/#using-the-honeycomb-opentelemetry-endpoint)
  then you'd also want to set `OTEL_EXPORTER_OTLP_HEADERS` and
  `OTEL_SERVICE_NAME`.

Then any time you build your project the build will export open telemetry
metrics.  The overhead of metrics export is negligible.

## Development

This repository uses Nix for development.  You can build this package entirely
using Nix for a specific version of `ghc` by running:

```ShellSession
$ nix develop .#ghc${MAJOR}${MINOR}
```

… replacing `${MAJOR}` and `${MINOR}` with the major and minor version of the
`ghc` that you're using.  For example, if you're using GHC 9.4, then you'd run:

```ShellSession
$ nix build .#ghc94
```

If you want to develop interactively using Cabal inside of a Nix shell, run:

```ShellSession
$ nix develop .#ghc${MAJOR}${MINOR}
```

Once you are inside that Nix shell, then you can use `cabal` commands, like
`cabal build` or `cabal repl`.  You can also use `ghcid` or launch your favorite
IDE from inside this shell.