instana-haskell-trace-sdk 0.5.0.0 → 0.5.0.1

raw patch · 6 files changed

+25/−11 lines, 6 files

Files

• CONTRIBUTING.md +2/−0
• ChangeLog.md +1/−1
• README.md +6/−2
• instana-haskell-trace-sdk.cabal +1/−1
• src/Instana/SDK/SDK.hs +14/−6
• test/integration/Instana/SDK/IntegrationTest/Metrics.hs +1/−1

@@ -65,6 +65,8 @@     * `instana-haskell-trace-sdk.cabal`     * `package.yaml`     * `test/integration/Instana/SDK/IntegrationTest/Metrics.hs` (assertion for `sensorVersion`)+* Update `README.md` with API changes.+* Update `CHANGELOG.md` (update/add entry) * Commit and push this change with a commit comment like `chore: version a.b.c.d` * Build the package with stack and upload it to Hackage:     * `stack haddock && stack sdist && stack upload .`

@@ -1,6 +1,6 @@ # Changelog for instana-haskell-trace-sdk -## Unreleased+## 0.5.0.0 - Add support for website monitoring back end correlation via Server-Timing. - Add support for website monitoring back end correlation via X-INSTANA-L/correlationType/correlationId. 

@@ -20,7 +20,7 @@  ``` extra-deps:-- instana-haskell-trace-sdk-0.5.0.0+- instana-haskell-trace-sdk-0.5.0.1 ```  Depending on the stack resolver you use, you might also need to add `aeson-extra` to your extra-deps:@@ -125,6 +125,8 @@  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 `withHttpExit` or `startHttpExit`/`completeExit` functions (see below). +The middleware plug-in will also add an additional HTTP response header (`Server-Timing`) to HTTP responses. This header enables website monitoring back end correlation.+ ``` import qualified Instana.Wai.Middleware.Entry as InstanaWaiMiddleware @@ -138,9 +140,11 @@  * `withRootEntry`: Creates an entry span that is the root of a trace (it has no parent span). * `withEntry`: Creates an entry span that has a parent span.-* `withHttpEntry`: A convenience function that examines an HTTP request for Instana tracing headers and creates an entry span. It will automatically add the correct metadata to the span. You do not need to handle incoming HTTP requests at all when using the Instana WAI middleware plug-in (see above).+* `withCorrelatedHttpEntry`: A convenience function that examines an incoming HTTP request for Instana tracing headers and creates an entry span. It will automatically add the correct metadata to the span. 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`. You do not need to handle incoming HTTP requests at all when using the Instana WAI middleware plug-in (see above).+* `withHttpEntry`: A convenience function that examines an incoming HTTP request for Instana tracing headers and creates an entry span. It will automatically add the correct metadata to the span. 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. You do not need to handle incoming HTTP requests at all when using the Instana WAI middleware plug-in (see above). * `withExit`: Creates an exit span. This can only be called inside a `withRootEntry` or an `withEntry` call, as an exit span needs an entry span as its parent. * `withHttpExit`: Creates an exit span for a given HTTP client request. It will automatically add the correct metadata to the span so it should be preferred to `withExit` when tracing outgoing HTTP requests. It will also add HTTP headers to the request to propagate the trace context downstream.+* `addWebsiteMonitoringBackEndCorrelation`: Adds an additional HTTP response header (`Server-Timing`) to the given HTTP response. This header 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 'withCorrelatedHttpEntry', which adds the response header automatically.  #### Low Level API/Explicit Start And Complete 

@@ -1,5 +1,5 @@ name:           instana-haskell-trace-sdk-version:        0.5.0.0+version:        0.5.0.1 synopsis:       SDK for adding custom Instana tracing support to Haskell applications. description:    Please also see the README on Github at <https://github.com/instana/haskell-trace-sdk#readme> homepage:       https://www.instana.com/

@@ -255,8 +255,9 @@   return result  --- |A convenience function that examines the given request for Instana tracing--- headers (https://docs.instana.io/core_concepts/tracing/#http-tracing-headers)+-- |A convenience function that examines the given incoming HTTP request for+-- Instana tracing headers+-- (https://docs.instana.io/core_concepts/tracing/#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. --@@ -265,6 +266,9 @@ -- monitoring back end correlation. Alternatively you can also call -- 'addWebsiteMonitoringBackEndCorrelation' with the WAI Response value before -- handing it off to WAI's 'respond' function.+--+-- You do not need to handle incoming HTTP requests at all when using the+-- Instana WAI middleware plug-in. withHttpEntry ::   MonadIO m =>   InstanaContext@@ -304,8 +308,9 @@       io  --- |A convenience function that examines the given request for Instana tracing--- headers (https://docs.instana.io/core_concepts/tracing/#http-tracing-headers)+-- |A convenience function that examines the given incoming HTTP request for+-- Instana tracing headers+-- (https://docs.instana.io/core_concepts/tracing/#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@@ -313,6 +318,9 @@ -- 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. withCorrelatedHttpEntry ::   MonadIO m =>   InstanaContext@@ -534,9 +542,9 @@         )  --- |Adds an additional HTTP response header (Server-Timing) to the given+-- |Adds an additional HTTP response header (Server-Timing) to the given HTTP -- response that enables website monitoring back end correlation. In case the--- respons already has a Server-Timing header, a value is appended to 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,

@@ -51,7 +51,7 @@               (EntityDataRequest.arguments entityData)           , assertLabelIs               "sensorVersion"-              "0.5.0.0"+              "0.5.0.1"               (EntityDataRequest.sensorVersion entityData)           , assertCounterSatisfies               "startTime"