[camel] branch main updated: CAMEL-19512: Add note in docs about backlog-tracing and InputStream headers.

[da...@apache.org]

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 <cl...@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,