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, so if you wrap your build in something like the hotel executable (from the hotel-california package) then you will get the correct duration for the outermost span.

This plugin also supports the standard BAGGAGE environment variable, 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 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:

$ 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:

$ nix build .#ghc94

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

$ 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.