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.8.0.0-inplace" '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)) :*: S1 ('MetaSel ('Just "disableW3cTraceCorrelation") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Bool)))))

type InstanaContext = InternalContext

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

addAnnotation :: MonadIO m => InstanaContext -> Annotation -> m ()

Adds an annotation 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.

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

Adds an annotation to the currently active span. Call this between startEntrystartRootEntrystartExit and completeEntry/completeExit or inside the IO action given to 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": "..." }, ... }

addAnnotationValueAt :: MonadIO m => InstanaContext -> Text -> AnnotationValue -> m ()

Adds an annotation with the given value 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": { ... "http": { "url": "..." }, ... }

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.

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 HTTP response that enables website monitoring back end correlation. In case the response already has a Server-Timing header, a value is appended to the existing Server-Timing list. This function needs be called while the HTTP entry span is still active. It can be used inside a withHttpEntry_ block or between startHttpEntry and completeEntry.

Client code should rarely have the need to call this directly. Instead, capture incoming HTTP requests with withHttpEntry, which adds the response header automatically and also captures the HTTP status code of the response. When not using withHttpEntry, the function postProcessHttpResponse should be preferred over this function, because it does both (capture the status code and add the Server-Timing header).

agentHost :: Config -> Maybe String

IP or host name of the Instana agent

agentPort :: Config -> Maybe Int

Port of the Instana agent

captureHttpStatus :: MonadIO m => InstanaContext -> Response -> m ()

Captures the status code of the HTTP response and adds it to the currently active span. If the status code is >= 500, the status message is also captured. This function needs be called while the HTTP entry span is still active. It can be used inside a withHttpEntry_ block or between startHttpEntry and completeEntry.

Client code should rarely have the need to call this directly. Instead, capture incoming HTTP requests with withHttpEntry, which captures the status code automatically and also adds the Server-Timing header for back end web site monitoring correlation. When not using withHttpEntry, the function postProcessHttpResponse should be preferred over this function, because it does both (capture the status code and add the Server-Timing header).

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.

currentParentId :: InstanaContext -> IO (Maybe String)

Retrieves the parent ID of the currently active span in the current thread.

currentSpan :: InstanaContext -> IO (Maybe SimpleSpan)

Provides the currently active span in a simple format fit for external use.

currentSpanId :: InstanaContext -> IO (Maybe String)

Retrieves the span ID of the currently active span in the current thread.

currentTraceId :: InstanaContext -> IO (Maybe String)

Retrieves the trace ID of the currently active trace in the current thread.

currentTraceIdInternal :: InstanaContext -> IO (Maybe Id)

Retrieves the trace ID of the currently active trace in 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.

isConnected :: InstanaContext -> IO Bool

Checks whether the SDK has a connection to an Instana agent.

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.

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

Processes the response of an HTTP entry. This function needs be called while the HTTP entry span is still active. It can be used inside a withHttpEntry_ block or between startHttpEntry and completeEntry.

This function accomplishes two things: * It captures the HTTP status code from the response and adds it as an annotation to the currently active span. * It adds an additional HTTP response header (Server-Timing) to the given HTTP response that enables website monitoring back end correlation. In case the response 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 withHttpEntry, which does both of these things automatically.

Clients should make sure to call this in the context provided above, that is, within withHttpEntry_ or between startHttpEntry and completeEntry but outside of blocks that create an exit span, that is, outside of withExit, withHttpExit and not between startExit and completeExit.

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.

setSynthetic :: MonadIO m => InstanaContext -> Bool -> m ()

Set the synthetic flag. This should only be set on entry spans. It will be silently ignored for other types of spans.

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. For incoming HTTP requests, prefer 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 Response -> m Response

A convenience function that examines the given incoming HTTP 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 capture the response HTTP status (and set the span's error count if it is 5xx). Finally, it will 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_.

You do not need to handle incoming HTTP requests at all when using the Instana WAI middleware plug-in.

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

A variant of withHttpEntry with a more general type signature, but less features. It will automatically continue the trace from incoming headers just like withHttpEntry does, but it will not capture the status code of the HTTP response or add the response header for website monitoring back end correlation (Server-Timing).

It is recommended to use withHttpEntry instead of this function, if possible. Alternatively, you can also call postProcessHttpResponse inside the withHttpEntry_ block to cover the two missing features mentioned above.

Note that you do not need to handle incoming HTTP requests at all when using the Instana WAI middleware plug-in.

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 withHttpEntry instead.