# `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
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: -plugin-package opentelemetry-plugin -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.