Instana.SDK.SDK

Instana.SDK.SDK is the main API of the Instana Haskell Trace SDK. Use one of initInstana, initConfiguredInstana, withInstana, or withConfiguredInstana to get an InstanaContext. Then use the context with any of the withRootEntry, withEntry, withExit functions for tracing.

Documentation

data Config

Configuration for the Instana SDK. Please use the defaultConfig function and then modify individual settings via record syntax For more information, see http://www.yesodweb.com/book/settings-types.

Instances

Eq Config

Defined in Instana.SDK.Config

Methods

(==) :: Config -> Config -> Bool

(/=) :: Config -> Config -> Bool

Generic Config

Defined in Instana.SDK.Config

Associated Types

type Rep Config :: Type -> Type

Methods

from :: Config -> Rep Config x

to :: Rep Config x -> Config

type Rep Config

Defined in Instana.SDK.Config

type Rep Config = D1 ('MetaData "Config" "Instana.SDK.Config" "instana-haskell-trace-sdk-0.5.0.0-CC1L5pLij5V4IZu4epwYU5" 'False) (C1 ('MetaCons "Config" 'PrefixI 'True) ((S1 ('MetaSel ('Just "agentHost") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe String)) :*: (S1 ('MetaSel ('Just "agentPort") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe Int)) :*: S1 ('MetaSel ('Just "serviceName") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe String)))) :*: (S1 ('MetaSel ('Just "forceTransmissionAfter") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe Int)) :*: (S1 ('MetaSel ('Just "forceTransmissionStartingAt") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe Int)) :*: S1 ('MetaSel ('Just "maxBufferedSpans") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Maybe Int))))))

type InstanaContext = InternalContext

A container for all the things the Instana SDK needs to do its work.

addHttpTracingHeaders :: MonadIO m => InstanaContext -> Request -> m Request

Adds the Instana tracing headers (https:/docs.instana.iocore_conceptstracing#http-tracing-headers) from the currently active span to the given HTTP client request.

addRegisteredData :: MonadIO m => InstanaContext -> Value -> m ()

Adds additional data to the currently active registered span. Call this between startEntrystartRootEntrystartExit and completeEntry/completeExit or inside the IO action given to with withEntrywithExitwithRootEntry. Can be called multiple times, data from multiple calls will be merged.

Note that this should only be used for registered spans, not for SDK spans. Use addTag for SDK spans instead.

addRegisteredDataAt :: (MonadIO m, ToJSON a) => InstanaContext -> Text -> a -> m ()

Adds additional meta data to the currently active registered span. Call this between startEntrystartRootEntrystartExit and completeEntry/completeExit or inside the IO action given to with withEntrywithExitwithRootEntry. The given path can be a nested path, with path fragments separated by dots, like "http.url". This will result in "data": { ... "http": { "url": "..." }, ... }

Note that this should only be used for registered spans, not for SDK spans. Use addTagAt for SDK spans instead.

addTag :: MonadIO m => InstanaContext -> Value -> m ()

Adds additional custom tags to the currently active span. Call this between startEntrystartRootEntrystartExit and completeEntry/completeExit or inside the IO action given to with withEntrywithExitwithRootEntry. Can be called multiple times, data from multiple calls will be merged.

This should be used for SDK spans instead of addRegisteredData.

addTagAt :: (MonadIO m, ToJSON a) => InstanaContext -> Text -> a -> m ()

Adds additional custom tags to the currently active span. Call this between startEntrystartRootEntrystartExit and completeEntry/completeExit or inside the IO action given to with withEntrywithExitwithRootEntry. The given path can be a nested path, with path fragments separated by dots, like "http.url". This will result in "data": { ... "sdk": { "custom": { "tags": { "http": { "url": "..." }, }, }, }, ... }

This should be used for SDK spans instead of addRegisteredDataAt.

addToErrorCount :: MonadIO m => InstanaContext -> Int -> m ()

Increments the error count for the currently active span by one. Call this between startEntrystartRootEntrystartExit and completeEntry/completeExit or inside the IO action given to with withEntrywithExitwithRootEntry if an error happens while processing the entry/exit.

addWebsiteMonitoringBackEndCorrelation :: MonadIO m => InstanaContext -> Response -> m Response

Adds an additional HTTP response header (Server-Timing) to the given response that enables website monitoring back end correlation. In case the respons already has a Server-Timing header, a value is appended to the existing Server-Timing list.

Client code should rarely have the need to call this directly. Instead, capture incoming HTTP requests with withCorrelatedHttpEntry, which adds the response header automatically.

agentHost :: Config -> Maybe String

IP or host name of the Instana agent

agentPort :: Config -> Maybe Int

Port of the Instana agent

completeEntry :: MonadIO m => InstanaContext -> m ()

Completes an entry span, to be called at the last possible moment before the call has been processed completely.

completeExit :: MonadIO m => InstanaContext -> m ()

Completes an exit span, to be called as soon as the remote call has returned.

currentTraceId :: InstanaContext -> IO (Maybe Id)

Retrieves the trace ID the current thread.

defaultConfig :: Config

Populates all config values as Nothing, so that the Instana SDK relies on environment variables or on its default config values (in this order) internally.

forceTransmissionAfter :: Config -> Maybe Int

Spans are usually buffered before being transmitted to the agent. This setting forces the transmission of all buffered spans after the given amount of milliseconds. Default: 1000.

forceTransmissionStartingAt :: Config -> Maybe Int

This setting forces the transmission of all buffered spans when the given number of spans has been buffered.

incrementErrorCount :: MonadIO m => InstanaContext -> m ()

Increments the error count for the currently active span by one. Call this between startEntrystartRootEntrystartExit and completeEntry/completeExit or inside the IO action given to with withEntrywithExitwithRootEntry if an error happens while processing the entry/exit.

This is an alias for `addToErrorCount instanaContext 1`.

initConfiguredInstana :: MonadIO m => Config -> m InstanaContext

Initializes the Instana SDK and the connection to the Instana agent, using the given Instana configuration.

Configuration settings that have not been set in the given configuration are read from the environment, falling back to default values.

initInstana :: MonadIO m => m InstanaContext

Initializes the Instana SDK and the connection to the Instana agent.

The configuration is read from the environment, falling back to default values.

maxBufferedSpans :: Config -> Maybe Int

Limits the number of spans to buffer. When the limit is reached, spans will be dropped. This setting is a safe guard against memory leaks from buffering excessive amounts of spans. It must be larger than forceTransmissionStartingAt.

readHttpTracingHeaders :: Request -> TracingHeaders

Reads the Instana tracing headers (https:/docs.instana.iocore_conceptstracing#http-tracing-headers) from the given request.

serviceName :: Config -> Maybe String

Overrides the default service name that is used in Instana.

setCorrelationId :: MonadIO m => InstanaContext -> Text -> m ()

Set the website monitoring correlation ID. This should only be set on root entry spans. It will be silently ignored for other types of spans.

setCorrelationType :: MonadIO m => InstanaContext -> Text -> m ()

Set the website monitoring correlation type. This should only be set on root entry spans. It will be silently ignored for other types of spans.

setServiceName :: MonadIO m => InstanaContext -> Text -> m ()

Override the name of the service for the associated call in Instana.

startEntry :: MonadIO m => InstanaContext -> String -> String -> SpanType -> m ()

Creates a preliminary/incomplete entry span, which should later be completed by calling completeEntry.

startExit :: MonadIO m => InstanaContext -> SpanType -> m ()

Creates a preliminary/incomplete exit span, which should later be completed with completeExit.

startHttpEntry :: MonadIO m => InstanaContext -> Request -> m ()

A convenience function that examines the given request for Instana tracing headers (https:/docs.instana.iocore_conceptstracing#http-tracing-headers) and either calls startRootEntry or startEntry, depending on the presence of absence of these headers.

startHttpExit :: MonadIO m => InstanaContext -> Request -> m Request

Creates a preliminary/incomplete http exit span, which should later be completed with completeExit. The Instana tracing headers are added to the request and the modified request value is returned (use the return value of this function to execute your request instead of the request value passed into this function).

startRootEntry :: MonadIO m => InstanaContext -> SpanType -> m ()

Creates a preliminary/incomplete root entry span, which should later be completed with completeEntry.

withConfiguredInstana :: MonadIO m => Config -> (InstanaContext -> m a) -> m a

Initializes the Instana SDK and the connection to the Instana agent, then calls the given function with the established connection, using the given Instana configuration.

Configuration settings that have not been set in the given configuration are read from the environment, falling back to default values.

withCorrelatedHttpEntry :: MonadIO m => InstanaContext -> Request -> m Response -> m Response

A convenience function that examines the given request for Instana tracing headers (https:/docs.instana.iocore_conceptstracing#http-tracing-headers) and wraps the given IO action either in startRootEntry or startEntry and completeEntry, depending on the presence or absence of these headers. It will also add (or append to) the HTTP response header (Server-Timing) that is used for website monitoring back end correlation. (The latter part is the difference to withHttpEntry, plus the slightly different type signature.)

This function should be preferred over withHttpEntry.

withEntry :: MonadIO m => InstanaContext -> String -> String -> SpanType -> m a -> m a

Wraps an IO action in startEntry and completeEntry. For incoming HTTP requests, prefer withCorrelatedHttpEntry or withHttpEntry instead.

withExit :: MonadIO m => InstanaContext -> SpanType -> m a -> m a

Wraps an IO action in startExit and completeExit.

withHttpEntry :: MonadIO m => InstanaContext -> Request -> m a -> m a

A convenience function that examines the given request for Instana tracing headers (https:/docs.instana.iocore_conceptstracing#http-tracing-headers) and wraps the given IO action either in startRootEntry or startEntry and completeEntry, depending on the presence or absence of these headers.

It is recommended to use withCorrelatedHttpEntry instead of this function to also automatically add the HTTP response header for website monitoring back end correlation. Alternatively you can also call addWebsiteMonitoringBackEndCorrelation with the WAI Response value before handing it off to WAI's respond function.

withHttpExit :: MonadIO m => InstanaContext -> Request -> (Request -> m a) -> m a

Wraps an IO action in startHttpExit and completeExit. The given action is accepted as a function (Request -> IO a) and is expected to use the provided request parameter for executing the HTTP request.

withInstana :: MonadIO m => (InstanaContext -> m a) -> m a

Initializes the Instana SDK and the connection to the Instana agent, then calls the given function with the established connection.

The configuration is read from the environment, falling back to default values.

withRootEntry :: MonadIO m => InstanaContext -> SpanType -> m a -> m a

Wraps an IO action in startRootEntry and completeEntry. For incoming HTTP requests, prefer withCorrelatedHttpEntry or withHttpEntry instead.