(camel) 19/25: CAMEL-23722: Document Spans/Process tabs in TUI, add --example to Getting Started

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch feature/CAMEL-23722-cli-docs-restructure
in repository https://gitbox.apache.org/repos/asf/camel.git

commit e1f8e39f679a238eac70f326856201bb0e6c1ed6
Author: Claus Ibsen <cl...@gmail.com>
AuthorDate: Tue Jun 9 20:25:10 2026 +0200

    CAMEL-23722: Document Spans/Process tabs in TUI, add --example to Getting Started
    
    Co-Authored-By: Claude <no...@anthropic.com>
    Signed-off-by: Claus Ibsen <cl...@gmail.com>
---
 .../ROOT/pages/camel-jbang-getting-started.adoc    | 22 ++++++++++++++
 .../modules/ROOT/pages/camel-jbang-tui.adoc        | 35 +++++++++++++++++++++-
 2 files changed, 56 insertions(+), 1 deletion(-)

diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc
index 1bdb88e9c39a..cdc8f2a3d1c8 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-getting-started.adoc
@@ -83,6 +83,28 @@ This works for all DSLs (YAML, Java, XML).
 TIP: Dev mode is the fastest way to prototype integrations.
 Keep it running while you iterate on your routes.
 
+== Try a built-in example
+
+Don't have a route yet? The CLI ships with a catalog of ready-to-run examples:
+
+[source,bash]
+----
+camel run --example
+----
+
+This lists all available examples grouped by difficulty (beginner, intermediate, advanced),
+with icons showing whether they are bundled (work offline), require Docker, or include Citrus tests.
+
+Run one directly:
+
+[source,bash]
+----
+camel run --example=timer-log
+camel run --example=rest-api --dev
+----
+
+TIP: Combine with `--dev` for live reload while exploring the example.
+
 === Running multiple files
 
 You can run several files together, even mixing DSLs:
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
index 251a3650f2b8..bc77fe6ebddc 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc
@@ -79,7 +79,7 @@ to any tab, or use *Tab* / *Shift+Tab* to cycle.
 | 7 | Health | Health check status.
 | 8 | Inspect | Message history and tracing -- step through exchanges processor by processor.
 | 9 | Errors | Failures with stack traces and exchange context.
-| 0 | More | Additional tabs: Beans, Browse, Circuit Breaker, Classpath, Configuration, Consumers, Inflight, Memory, Metrics, Startup, Threads.
+| 0 | More | Additional tabs: Beans, Browse, Circuit Breaker, Classpath, Configuration, Consumers, Inflight, Memory, Metrics, Process, Spans, Startup, Threads.
 |===
 
 Tab badges show live counts -- the Errors tab shows a red badge when errors exist,
@@ -225,6 +225,39 @@ For deeper troubleshooting, switch to the Inspect tab (Tab 8) and use the diagra
 This combination of error details + visual diagram replay gives you a complete picture of
 what went wrong and why -- without leaving the terminal.
 
+== OpenTelemetry Spans
+
+The Spans tab (under More, shortcut *o*) visualizes OpenTelemetry traces collected from your
+running integration. It shows every span with trace ID, span name, kind, status, duration,
+and Camel-specific context (route ID, processor ID).
+
+Run your integration with OpenTelemetry enabled:
+
+[source,bash]
+----
+camel run my-route.yaml --dep=camel:opentelemetry
+----
+
+Features:
+
+* *Waterfall view* -- spans displayed as a timeline showing parent-child relationships
+  and duration bars, color-coded from green (fast) to red (slow)
+* *Trace grouping* -- spans grouped by trace ID so you can follow a complete request
+  across multiple routes and components
+* *Camel-only filter* -- toggle to show only Camel-originated spans, hiding framework
+  and library spans
+* *Sort and search* -- sort by trace ID, route, status, duration, or span count;
+  filter with text search
+* *Error highlighting* -- failed spans (status ERROR) are highlighted in red
+
+This is especially useful for understanding latency in multi-route integrations and for
+correlating Camel processing with external service calls (HTTP, database, messaging).
+
+== Process Information
+
+The Process tab (under More, shortcut *p*) shows JVM process details for the selected
+integration: Java version, PID, uptime, command-line arguments, and system properties.
+
 == Actions Menu (F2)
 
 Press *F2* to open the actions menu with quick access to common operations: