This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push: new d3a30347668 CAMEL-19512: Add note in docs about backlog-tracing and InputStream headers. d3a30347668 is described below commit d3a303476687d1238815a7b5556e90ffdd8c61ed Author: Claus Ibsen <claus.ib...@gmail.com> AuthorDate: Fri Jul 7 22:33:33 2023 +0200 CAMEL-19512: Add note in docs about backlog-tracing and InputStream headers. --- docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc | 13 +++++++++++++ .../modules/ROOT/pages/camel-3x-upgrade-guide-3_21.adoc | 4 ++++ .../modules/ROOT/pages/camel-4-migration-guide.adoc | 4 ++++ 3 files changed, 21 insertions(+) diff --git a/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc b/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc index 0b02dfd5a67..9a3dd86686a 100644 --- a/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc +++ b/docs/user-manual/modules/ROOT/pages/backlog-tracer.adoc @@ -132,3 +132,16 @@ And in Spring Boot you can enable this in the `application.properties` file: camel.springboot.backlog-tracing = true ---- +=== Tracing payloads of InputStream types + +Beware that when enabling backlog tracing, and the message payloads is streaming types (such as `java.io.InputStream`), +then the backlog tracer will read the payload and make a copy as a _trace_ that are stored in the backlog tracer. +Then monitoring tooling is able to view these _traced_ events. + +When working with `InputStream` types then Camel has xref:stream-caching.adoc[] that is able to automatic +make such types _safe_ to use as they are cached and able to be _re-read_. See more details at xref:stream-caching.adoc[]. + +However, Camel's stream caching is **ONLY** for message body. Having message headers of type `InputStream` is discouraged +and not common use. If you add custom message headers, then its recommended to **NOT** use streaming types, but +convert these headers into `String` or `byte[]` or other standard Java types that are in-memory and _safe_ to re-read. + diff --git a/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide-3_21.adoc b/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide-3_21.adoc index d1b675520e1..3104128f0dc 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide-3_21.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-3x-upgrade-guide-3_21.adoc @@ -18,6 +18,10 @@ The xref:tracer.adoc[Tracer] and xref:backlog-tracer.adoc[Backlog Tracer] no lon from routes that was created by Rest DSL or route templates or Kamelets. You can turn this on, by setting `traceTemplates=true` in the tracer. +The xref:backlog-tracer.adoc[Backlog Tracer] has been enhanced and _fixed_ to trace message headers (also streaming types). +This means that previously headers of type `InputStream` was not traced before, but is now included. This could mean that +the header stream is positioned at end, and logging the header afterward, may appear as the header value is empty. + ==== UseOriginalMessage / UseOriginalBody When `useOriginalMessage` or `useOriginalBody` is enabled in `OnException`, `OnCompletion` or error handlers, diff --git a/docs/user-manual/modules/ROOT/pages/camel-4-migration-guide.adoc b/docs/user-manual/modules/ROOT/pages/camel-4-migration-guide.adoc index a458d72556c..cc676e92136 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-4-migration-guide.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-4-migration-guide.adoc @@ -130,6 +130,10 @@ The xref:tracer.adoc[Tracer] and xref:backlog-tracer.adoc[Backlog Tracer] no lon from routes that was created by Rest DSL or route templates or Kamelets. You can turn this on, by setting `traceTemplates=true` in the tracer. +The xref:backlog-tracer.adoc[Backlog Tracer] has been enhanced and _fixed_ to trace message headers (also streaming types). +This means that previously headers of type `InputStream` was not traced before, but is now included. This could mean that +the header stream is positioned at end, and logging the header afterward, may appear as the header value is empty. + == UseOriginalMessage / UseOriginalBody When `useOriginalMessage` or `useOriginalBody` is enabled in `OnException`, `OnCompletion` or error handlers,