opentelemetry-plugin: GHC plugin for open telemetry

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

No 'category' field.
These packages miss upper bounds: - bytestring - containers - hs-opentelemetry-propagator-w3c - mwc-random - text - unordered-containers Please add them, using `cabal gen-bounds` for suggestions. For more information see: https://pvp.haskell.org/

This package provides a GHC plugin that exports each module's build times to an open telemetry collector. See the included README below for more details.

[Skip to Readme]

Properties

Versions	1.0.0, 1.0.0, 1.1.0, 1.1.1
Change log	CHANGELOG.md
Dependencies	base (>=4.15.0.0 && <5), bytestring, containers, ghc (>=9.2 && <9.8), hs-opentelemetry-api (>=0.1.0.0 && <0.2), hs-opentelemetry-propagator-w3c, hs-opentelemetry-sdk (>=0.0.3.0 && <0.1), mwc-random (>=0.13.1.0), text, unordered-containers [details]
License	BSD-3-Clause
Copyright	2023 Mercury Technologies
Author	Mercury Technologies
Maintainer	gabriella@mercury.com
Uploaded	by GabrielGonzalez at 2023-10-03T21:51:17Z

Modules

[Index] [Quick Jump]

OpenTelemetry
- OpenTelemetry.Plugin

Downloads

opentelemetry-plugin-1.0.0.tar.gz [browse] (Cabal source package)
Package description (as included in the package)

Maintainer's Corner

Package maintainers

GabrielGonzalez, parsonsmatt

For package maintainers and hackage trustees

edit package information

Readme for opentelemetry-plugin-1.0.0

[back to package description]

`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

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