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

Methods

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

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

Generic Config

Associated Types

type Rep Config :: * -> *

Methods

from :: Config -> Rep Config x

to :: Rep Config x -> Config

type Rep Config

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

type InstanaContext = InternalContext

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

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.

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.

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.

agentHost :: Config -> Maybe String

IP or host name of the Instana agent

agentName :: Config -> Maybe String

When establishing a connection to the Instana agent, the SDK validates the Instana agent's Server HTTP response header. Should you have changed the Server name on the agent side, you can use parameter to provide the name to match that header against.

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.

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.

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.

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

Wraps an IO action in startEntry and completeEntry.

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.

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.