instana-haskell-trace-sdk: SDK for adding custom Instana tracing support to Haskell applications.

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.


Please also see the README on Github at

[Skip to ReadMe]


Dependenciesaeson, aeson-extra, base (>=4.7 && <5), binary, bytestring, containers, directory, ekg-core, exceptions, hslogger, http-client, http-client-tls, http-types, instana-haskell-trace-sdk, network, process, random, regex-base, regex-tdfa, retry, scientific, servant, servant-server, stm, sysinfo, text, time, transformers, unix, unordered-containers, wai, warp [details]
Copyright2018 Instana, Inc.
AuthorBastian Krol
Home page
Bug tracker
Source repositoryhead: git clone
Executablesinstana-haskell-test-wai-with-middleware-server, instana-haskell-test-wai-server, instana-haskell-agent-stub, instana-haskell-example-exe
UploadedFri Feb 15 23:06:22 UTC 2019 by basti1302





development mode - warnings let compilation fail


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainers' corner

For package maintainers and hackage trustees

Readme for instana-haskell-trace-sdk-

[back to package description]

Instana Haskell Trace SDK   Build Status

Monitor your Haskell application with Instana! 🎉


The Instana Haskell Trace SDK is a labor of love from some of our engineers and work on it is done in their spare time. Haskell is currently not a platform that we officialy support. The experience may differ from other programming languages and platforms that Instana actively supports (such as Java, .NET, Node.js, Python, Ruby, Go, PHP, ...). That said, the SDK is a fully functional piece of software, so don't let this disclaimer discourage you from using it. If you use Instana or consider using it and Haskell support is crucial for you, make sure to give us a ping and let's talk about it.

What The Haskell Trace SDK Is And What It Is Not

The Instana Haskell Trace SDK does not support automatic instrumentation/tracing in the way we support it in most other languages. Instead, the SDK enables you to create spans manually, much like the Instana Trace SDK for Java does. Besides offering a convenient API to create spans, the Haskell Trace SDK also takes care of establishing a connection to the Instana Agent and sending spans to the agent in an efficient way, that does not impede the performance of your production code. Last but not least, it collects runtime metrics and reports them to Instana.


To use the Instana Haskell Trace SDK in your application, add instana-haskell-trace-sdk to your dependencies (for example to the build-depends section of your cabal file). If you are using stack you might need to add the SDK (with the version number you want to use) to the extra-deps section in your stack.yaml file:

- instana-haskell-trace-sdk-



Before using the SDK, you need to initialize it once, usually during application startup.

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do
  -- ... initialize things ...

  -- initialize Instana
  instana <- InstanaSDK.initInstana

  -- ... initialize more things

The value instana :: Instana.SDK.InstanaContext that is returned by InstanaSDK.initInstana is required for all further calls, that is, for creating spans that will be send to the agent. The SDK will try to connect to an agent (asynchronous, in a a separate thread) as soon as it receives the initInstana call.

The SDK can be configured via environment variables or directly in the code by passing configuration parameters to the initialization function, or both.

If you would like to pass configuration parameters programatically, use initConfiguredInstana instead of initInstana:

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do

  -- Example snippet for using the Instana SDK and providing a configuration
  -- (agent host, port, ...) directly in code. You only need to specify the
  -- configuration values you are interested in and can omit everything else
  -- (see
    config =
        { InstanaSDK.agentHost = Just ""
        , InstanaSDK.agentPort = Just 42699
        , InstanaSDK.forceTransmissionAfter = Just 1000
        , InstanaSDK.forceTransmissionStartingAt = Just 500
        , InstanaSDK.maxBufferedSpans = Just 1000
  instana <- InstanaSDK.initConfiguredInstana config

For configuration parameters that are omitted when creating the config record or are set to Nothing, the SDK will fall back to environment variables (see below) and then to default values.

There are also bracket-style variants of the initialization function, called withInstana and withConfiguredInstana:

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do
  InstanaSDK.withInstana runApp

runApp :: InstanaContext -> IO ()
runApp instana = do
  -- do your thing here :-)

or, with bracket style and a configuration record:

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do
    config =
        { InstanaSDK.agentHost = Just ""
        , InstanaSDK.agentPort = Just 42699
        , InstanaSDK.forceTransmissionAfter = Just 1000
        , InstanaSDK.forceTransmissionStartingAt = Just 500
        , InstanaSDK.maxBufferedSpans = Just 1000

  InstanaSDK.withConfiguredInstana config runApp

runApp :: InstanaContext -> IO ()
runApp instana = do
  -- do your thing here :-)

Creating Spans

Trace HTTP Entries Automatically

You can let the SDK automatically create entry spans for all incoming HTTP requests in a WAI application by using it as a WAI middleware plug-in. Note that exit spans still need to be created manually via the withExit or startExit/stopExit functions (see below).

import qualified Instana.Wai.Middleware.Entry as InstanaWaiMiddleware

main = do 3000 $ InstanaWaiMiddleware.traceHttpEntries instana $ app

Bracket Style (High Level API)

All functions starting with with accept (among other parameters) an IO action. The SDK will start a span before, then execute the given IO action and complete the span afterwards. Using this style is recommended over the low level API that requires you to start and complete spans yourself.

Low Level API/Explicit Start And Complete

Configuration Via Environment Variables

Instead of configuring the SDK programatically, as seen above, it can also be configured via environment variables:

Configure Debug Logging

If required, the Instana Haskell SDK can produce logs via hslogger. Under normal circumstances, the SDK does not emit any log output at all. It will only output log messages when logging is explicitly enabled via certain environment variables. This can be useful to troubleshoot tracing in production settings or during development.

Logging Related Environment Variables


Setting up hslogger correctly inside a library like the Instana Haskell SDK (as opposed to an application which has full control) can be tricky. For the Instana Haskell SDK to be able to correctly configure hslogger, it is important to know whether the app in question (or some part of it) already uses hslogger. In particular, does some part of the code set a handler on hslogger's root logger? Is a call like the following executed somewhere in the application?

import System.Log.Logger (rootLoggerName, setHandlers, updateGlobalLogger)

updateGlobalLogger rootLoggerName $ setHandlers [...]

If this is the case, you can simply use INSTANA_LOG_LEVEL (or INSTANA_LOG_LEVEL_STDOUT) without further configuration. If the app in question does not use hslogger, that is, if no setHandler call on rootLoggerName is executed, you should also set INSTANA_OVERRIDE_HSLOGGER_ROOT_HANDLER to a non-empty string (for example, INSTANA_OVERRIDE_HSLOGGER_ROOT_HANDLER=true).

Troubleshooting Tracing In Production

If your app already uses hslogger, use:

Otherwise, use:


During development (that is, when working on the Instana Haskell SDK), use either


depending on whether the application already uses and configures hslogger. The application example-app that is contained in the Instana Haskell SDK's repo configures hslogger, so simply using INSTANA_LOG_LEVEL_STDOUT=DEBUG is correct.