Safe Haskell | None |
---|---|
Language | Haskell2010 |
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.
Synopsis
- data Config
- type InstanaContext = InternalContext
- addHttpTracingHeaders :: MonadIO m => InstanaContext -> Request -> m Request
- addRegisteredData :: MonadIO m => InstanaContext -> Value -> m ()
- addRegisteredDataAt :: (MonadIO m, ToJSON a) => InstanaContext -> Text -> a -> m ()
- addTag :: MonadIO m => InstanaContext -> Value -> m ()
- addTagAt :: (MonadIO m, ToJSON a) => InstanaContext -> Text -> a -> m ()
- addToErrorCount :: MonadIO m => InstanaContext -> Int -> m ()
- addWebsiteMonitoringBackEndCorrelation :: MonadIO m => InstanaContext -> Response -> m Response
- agentHost :: Config -> Maybe String
- agentPort :: Config -> Maybe Int
- completeEntry :: MonadIO m => InstanaContext -> m ()
- completeExit :: MonadIO m => InstanaContext -> m ()
- currentTraceId :: InstanaContext -> IO (Maybe Id)
- defaultConfig :: Config
- forceTransmissionAfter :: Config -> Maybe Int
- forceTransmissionStartingAt :: Config -> Maybe Int
- incrementErrorCount :: MonadIO m => InstanaContext -> m ()
- initConfiguredInstana :: MonadIO m => Config -> m InstanaContext
- initInstana :: MonadIO m => m InstanaContext
- maxBufferedSpans :: Config -> Maybe Int
- readHttpTracingHeaders :: Request -> TracingHeaders
- serviceName :: Config -> Maybe String
- setCorrelationId :: MonadIO m => InstanaContext -> Text -> m ()
- setCorrelationType :: MonadIO m => InstanaContext -> Text -> m ()
- setServiceName :: MonadIO m => InstanaContext -> Text -> m ()
- startEntry :: MonadIO m => InstanaContext -> String -> String -> SpanType -> m ()
- startExit :: MonadIO m => InstanaContext -> SpanType -> m ()
- startHttpEntry :: MonadIO m => InstanaContext -> Request -> m ()
- startHttpExit :: MonadIO m => InstanaContext -> Request -> m Request
- startRootEntry :: MonadIO m => InstanaContext -> SpanType -> m ()
- withConfiguredInstana :: MonadIO m => Config -> (InstanaContext -> m a) -> m a
- withCorrelatedHttpEntry :: MonadIO m => InstanaContext -> Request -> m Response -> m Response
- withEntry :: MonadIO m => InstanaContext -> String -> String -> SpanType -> m a -> m a
- withExit :: MonadIO m => InstanaContext -> SpanType -> m a -> m a
- withHttpEntry :: MonadIO m => InstanaContext -> Request -> m a -> m a
- withHttpExit :: MonadIO m => InstanaContext -> Request -> (Request -> m a) -> m a
- withInstana :: MonadIO m => (InstanaContext -> m a) -> m a
- withRootEntry :: MonadIO m => InstanaContext -> SpanType -> m a -> m a
Documentation
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 Source # | |
Generic Config Source # | |
type Rep Config Source # | |
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 Source #
A container for all the things the Instana SDK needs to do its work.
addHttpTracingHeaders :: MonadIO m => InstanaContext -> Request -> m Request Source #
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 () Source #
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 () Source #
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 () Source #
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 () Source #
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 () Source #
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 Source #
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.
completeEntry :: MonadIO m => InstanaContext -> m () Source #
Completes an entry span, to be called at the last possible moment before the call has been processed completely.
completeExit :: MonadIO m => InstanaContext -> m () Source #
Completes an exit span, to be called as soon as the remote call has returned.
currentTraceId :: InstanaContext -> IO (Maybe Id) Source #
Retrieves the trace ID the current thread.
defaultConfig :: Config Source #
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 Source #
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 Source #
This setting forces the transmission of all buffered spans when the given number of spans has been buffered.
incrementErrorCount :: MonadIO m => InstanaContext -> m () Source #
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 Source #
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 Source #
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 Source #
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 Source #
Reads the Instana tracing headers (https:/docs.instana.iocore_conceptstracing#http-tracing-headers) from the given request.
serviceName :: Config -> Maybe String Source #
Overrides the default service name that is used in Instana.
setCorrelationId :: MonadIO m => InstanaContext -> Text -> m () Source #
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 () Source #
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 () Source #
Override the name of the service for the associated call in Instana.
startEntry :: MonadIO m => InstanaContext -> String -> String -> SpanType -> m () Source #
Creates a preliminary/incomplete entry span, which should later be completed
by calling completeEntry
.
startExit :: MonadIO m => InstanaContext -> SpanType -> m () Source #
Creates a preliminary/incomplete exit span, which should later be completed
with completeExit
.
startHttpEntry :: MonadIO m => InstanaContext -> Request -> m () Source #
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 Source #
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 () Source #
Creates a preliminary/incomplete root entry span, which should later be
completed with completeEntry
.
withConfiguredInstana :: MonadIO m => Config -> (InstanaContext -> m a) -> m a Source #
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 Source #
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 Source #
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 Source #
Wraps an IO action in startExit
and completeExit
.
withHttpEntry :: MonadIO m => InstanaContext -> Request -> m a -> m a Source #
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 Source #
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 Source #
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 Source #
Wraps an IO action in startRootEntry
and completeEntry
. For incoming
HTTP requests, prefer withCorrelatedHttpEntry
or withHttpEntry
instead.