opentelemetry-plugin: GHC plugin for open telemetry

[ bsd3, library, unclassified ] [ Propose Tags ] [ Report a vulnerability ]

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]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Candidates

Versions [RSS] 1.0.0, 1.1.0, 1.1.1
Change log CHANGELOG.md
Dependencies base (>=4.18.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), stm, stm-containers, text, transformers, unordered-containers [details]
License BSD-3-Clause
Copyright 2023 Mercury Technologies
Author Mercury Technologies
Maintainer gabriella@mercury.com
Uploaded by parsonsmatt at 2024-10-16T17:40:14Z
Distributions NixOS:1.1.1
Downloads 108 total (2 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-10-20 [all 1 reports]

Readme for opentelemetry-plugin-1.1.1

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