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 <[email protected]>
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,
