This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch CAMEL-23672-tui-docs in repository https://gitbox.apache.org/repos/asf/camel.git
commit 0521bd6c270730ea7f0b455d27425f93d43adf38 Author: Claus Ibsen <[email protected]> AuthorDate: Sun Jun 7 09:41:12 2026 +0200 CAMEL-23672: TUI - Improve and expand documentation Co-Authored-By: Claude <[email protected]> Signed-off-by: Claus Ibsen <[email protected]> --- .../modules/ROOT/pages/camel-jbang-tui.adoc | 450 +++++++++++++++------ 1 file changed, 323 insertions(+), 127 deletions(-) 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 9913586a5cbc..251a3650f2b8 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-tui.adoc @@ -3,8 +3,8 @@ *Available as of Camel 4.21* Camel TUI is a terminal dashboard for developing, prototyping, and understanding Camel integrations. -It opens up the world of Camel with visual feedback -- you can see your route topology, watch messages -flow through processors, inspect exchange state at every step, and understand what Camel actually does +It makes your integration visible -- you can see your route topology, watch messages flow through +processors, step through exchanges like scrubbing through a video timeline, and understand what Camel actually does with your routes. No more black box. image::jbang/camel-tui-topology-overview.svg[TUI Overview showing multiple routes] @@ -12,39 +12,13 @@ image::jbang/camel-tui-topology-overview.svg[TUI Overview showing multiple route NOTE: This module is in *Preview* status. The TUI is designed for development and prototyping, not production monitoring. -== Why Use the TUI? - -Most integration frameworks give you "run and log" -- you write routes, start the app, and stare at -log output hoping to understand what happens. Camel TUI takes a different approach: it makes your -integration visible and interactive. - -*Camel is not a black box.* -The interactive route topology diagram shows how your routes connect -- which endpoints feed into which routes, -where messages fan out, and where failures happen. Drill into individual routes to see every processor -and EIP in the chain. Watch message counts update in real time. This is the architecture you designed, -rendered live in your terminal. - -image::jbang/camel-tui-topology-diagram.svg[Diagram topology view] - -*Understand what happens to your messages.* -Message tracing shows the exact path each exchange takes through your routes, with the message body, -headers, properties, and variables at every processing step. The errors tab collects failures with full -stack traces. No more grepping through log files -- the TUI organizes this information for you. - -*Prototype fast.* -Run built-in examples directly from the TUI, send test messages to any endpoint, restart routes -on the fly, and see the effect immediately. The TUI auto-discovers every running Camel integration -with zero configuration. +== Getting Started -*AI and humans working together.* -The built-in MCP server lets AI coding assistants (like Claude Code) see everything you see in the TUI -- -and more. The AI can read structured route data, inspect message traces, send test messages, -and annotate the diagram with highlights and labels. You get an AI pair-programmer that truly -understands your running integration, not just your source code. +You can start using the TUI in two ways: with your own route, or by running one of the built-in examples. -== Getting Started +=== Option 1: Your Own Route -Start a Camel integration: +Start a Camel integration in one terminal: [source,bash] ---- @@ -58,148 +32,370 @@ Open the TUI in another terminal: camel tui ---- -Or try the built-in examples directly from the TUI: press *F2* and select _Run an example_. +The TUI auto-discovers every running Camel integration on your machine -- no configuration needed. + +image::jbang/camel-tui-hello-overview.svg[TUI showing a simple hello route] + +=== Option 2: Built-in Examples + +Don't have a route yet? The TUI ships with a catalog of ready-to-run examples. +Open the TUI and press *F2*, then select _Run an example_: + +[source,bash] +---- +camel tui +---- + +. Press *F2* to open the actions menu +. Select *Run an example...* +. Browse the example catalog -- type to filter by name +. Press *Enter* to launch the selected example + +The example starts running in the background. The TUI auto-selects it as soon as it appears. +From there you can explore tabs, watch messages flow, inspect the route diagram, and experiment. + +If an example requires infrastructure (like Kafka or a database), the TUI automatically starts the +required Docker containers before launching the example. A notification in the footer shows the +progress. TIP: Press *F1* on any screen for context-sensitive help. -The TUI is designed to be self-discoverable -- keyboard shortcuts are shown in the footer, -and help pages explain every tab and feature. +Keyboard shortcuts are always shown in the footer bar. + +== Tabs Overview + +The TUI organizes information into tabs. Press number keys *1* through *0* to jump directly +to any tab, or use *Tab* / *Shift+Tab* to cycle. + +[cols="1,2,5",options="header"] +|=== +| Key | Tab | What It Shows + +| 1 | Overview | All running integrations and infrastructure services. Start here. +| 2 | Log | Real-time application logs with search and filtering. +| 3 | Diagram | Visual route topology with drill-down into individual routes. +| 4 | Routes | Route list with message counts, throughput, and processing times. +| 5 | Endpoints | All registered endpoints with usage statistics. +| 6 | HTTP | HTTP endpoints with details. +| 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. +|=== + +Tab badges show live counts -- the Errors tab shows a red badge when errors exist, +Health shows a badge when checks are DOWN, and Routes shows the route count. == Route Topology Diagram -The Diagram tab renders the route topology as interactive ASCII art. It shows how routes +The Diagram tab (Tab 3) renders the route topology as interactive ASCII art. It shows how routes connect to each other through shared endpoints (direct, seda, kafka, etc.). -* Navigate between routes with arrow keys, drill into a route with *Enter* -* Toggle external endpoints (kafka brokers, HTTP endpoints) with *e* -* Toggle metrics overlay (message counts) with *m* -* View route source code with *c* +image::jbang/camel-tui-topology-diagram.svg[Diagram topology view] -image::jbang/camel-tui-topology-diagram-external.svg[Diagram with external endpoints visible] +=== Topology View + +The topology shows all routes as boxes, connected by arrows: + +* *Trigger routes* (timer, cron, etc.) appear at the top +* *Downstream routes* appear below, connected by directed arrows +* Route boxes show the route ID, the `from` endpoint, and metrics when enabled + +Navigate between route boxes with arrow keys. When a route is selected, an *Info panel* appears +on the left showing state, uptime, throughput, exchange counts, and processing times. + +=== Drill-Down into Routes + +Press *Enter* on a selected route to drill down into its internal EIP structure. Each processor +and EIP node is displayed with its type (colored by category), endpoint URI, and per-node statistics. image::jbang/camel-tui-topology-diagram-drilldown.svg[Drill-down showing internal processors] -== AI Integration (MCP) -- Optional +Nodes that connect to other routes show a *Enter* indicator -- press *Enter* to jump directly +to the linked route. Navigation history is maintained as a breadcrumb stack: press *Esc* to go +back to the previous route, and eventually back to the topology view. -The TUI includes an embedded https://modelcontextprotocol.io/[MCP] (Model Context Protocol) server -that lets AI coding assistants interact with the dashboard programmatically. This turns the TUI -into a bridge between your running Camel integration and an AI agent. +Press *t* to jump straight back to the topology from any depth. -The TUI is fully functional on its own -- AI integration is entirely optional. You get the complete -dashboard experience with just `camel tui`. The MCP server adds a layer on top for AI-assisted -workflows when you want it. +=== External Endpoints -An AI agent connected to the TUI has access to a remarkable amount of information: the complete -route topology as a structured graph, every route's statistics and throughput, message traces with -body/headers/properties at each step, error details with stack traces, endpoint usage, health checks, -log entries, JVM metrics, and even the integration's source files. This is far more context than -an AI gets from reading source code alone -- it sees your integration *running*. +Press *e* to cycle through three modes for external endpoints: -=== Enabling MCP +* *off* -- only route-to-route connections shown +* *edges* -- external systems (kafka brokers, HTTP endpoints, databases) shown as dashed boxes +* *all* -- routes sharing an external endpoint are connected through an intermediary box + +image::jbang/camel-tui-topology-diagram-external.svg[Diagram with external endpoints visible] + +=== Metrics and Source Code + +* Press *m* to toggle metrics overlay (message counts on each node) +* Press *c* to view the source code of the selected route, with syntax highlighting +* Press *n* to toggle description labels on/off + +== Message Insight + +The Inspect tab (Tab 8) lets you step through an exchange processor by processor -- like +scrubbing through a video timeline of your message's journey. This is the key to understanding +what Camel does with your data at every step. + +=== History of Last Exchange + +When you open the Inspect tab, it shows the last completed exchange. The top panel lists +every processing step with: + +* *Step number* and direction (--> or <--) +* *Route* and *Node ID* of the processor +* *BHPV* change indicators -- letters light up in yellow when Body, Headers, Properties, + or Variables changed at that step +* *Elapsed* time per step + +Select a step with arrow keys, and the detail panel below shows the full exchange state: +body content, headers, properties, and variables at that exact point in the processing chain. + +=== Controlling What You See + +Toggle sections of the detail view: + +* *b* -- show/hide message body +* *h* -- show/hide headers +* *p* -- show/hide exchange properties +* *v* -- show/hide exchange variables +* *w* -- toggle word wrap +* *n* -- toggle description/processor labels + +=== Waterfall View + +Press *g* to switch to the waterfall view -- a horizontal bar chart showing how long each +processor took. This makes it easy to spot bottlenecks: long bars stand out immediately. +The selected step is highlighted with `>>` and processing times are color-coded from green +(fast) to red (slow). + +=== Replay on the Diagram + +Press *d* to overlay the message path on the route topology diagram. This is where the +timeline replay comes alive: + +* The diagram highlights which route and processor handled the message at each step +* Use *Up/Down* arrows to step forward and backward through the path +* An *Info panel* on the left shows the exchange state (body, headers, properties, variables) + at the current step -- values that changed from the previous step are highlighted in yellow +* Step through the entire exchange to watch how the message payload transforms as it flows + through processors, filters, and content-based routers +* Press *Enter* on a route node to drill down into its internal EIP structure while replaying +* Press *Esc* to go back, *t* to return to the topology view +* Press *i* to cycle the info panel size (narrow / wide / full) + +This is especially powerful for understanding complex multi-route flows where messages are +routed through direct, seda, or kafka endpoints between routes. + +=== Live Tracing + +When you run your integration with tracing enabled: [source,bash] ---- -camel tui --mcp +camel run my-route.yaml --trace ---- -This starts an MCP server on `localhost:8123` (configurable with `--mcp-port`). -The server is bound to `127.0.0.1` only -- it never listens on external interfaces. +The Inspect tab gains a live trace panel showing every exchange as it flows through the system. +Each exchange is listed with its timestamp, starting route, status (Processing/Done/Failed), +elapsed time, and step count. Press *Enter* to drill into an exchange and see every processor +step -- the same step-by-step view and diagram replay work here too. -When MCP is active, the TUI footer shows the connection status (e.g., `MCP :8123 (claude-code)`). -Use *F2* → _MCP Info_ to see server details and _MCP Log_ to view the tool call history. +Use *s* to cycle sort order (time, route, elapsed, exchange) and *S* to reverse. +Press *F5* to clear captured traces. -=== Connecting an AI Agent +== Troubleshooting Errors -To connect Claude Code to the TUI, add the MCP server to your project configuration -(`.mcp.json` in your project root): +The Errors tab (Tab 9) collects failures with full stack traces and exchange context. +When errors occur, a red badge appears on the tab. -[source,json] ----- -{ - "mcpServers": { - "camel-tui": { - "type": "url", - "url": "http://localhost:8123/mcp"; - } - } -} ----- +image::jbang/camel-tui-topology-errors.svg[Errors tab with failure details] -Once connected, the AI agent can see and interact with the TUI just as you do. +For deeper troubleshooting, switch to the Inspect tab (Tab 8) and use the diagram replay +(press *d*) to visualize exactly where the failure occurred: -=== What AI Agents Can Do +* Failed steps are highlighted in red on the diagram +* Step through the failing exchange to see the message state at each processor + leading up to the failure +* The Info panel shows the exception message and which node threw it +* Compare the message body and headers before and after the failing step + to understand what triggered the error -The MCP server exposes a comprehensive set of tools organized by purpose: +This combination of error details + visual diagram replay gives you a complete picture of +what went wrong and why -- without leaving the terminal. -==== Observe +== Actions Menu (F2) -* *tui_get_screen* -- Read the current screen content (exactly what you see) -* *tui_get_state* -- Get structured state: active tab, selected integration, footer actions -* *tui_get_table* -- Read table data as structured JSON (routes, endpoints, health, etc.) -* *tui_get_log* -- Query recent log entries with level and text filtering -* *tui_get_errors* -- Get structured error data with stack traces and exchange details -* *tui_get_history* -- Read trace data: message body, headers, properties at each processing step -* *tui_get_topology* -- Get the route graph as JSON (nodes and edges) -* *tui_get_diagram* -- Get the topology diagram as text art -* *tui_get_readme* -- Read the integration's README documentation -* *tui_get_files* -- List and read the integration's source files +Press *F2* to open the actions menu with quick access to common operations: -==== Navigate +[cols="2,5",options="header"] +|=== +| Action | Description + +| Send Message | Send a test message to any route with custom body, headers, and exchange pattern. +| Run an example... | Browse and launch built-in Camel examples from the catalog. +| Run from folder... | Run routes from a local directory. +| Run Dev/Infra Service... | Start infrastructure services (Kafka, databases, etc.) in Docker. +| Browse Files... | Browse the integration's source files with syntax highlighting. +| Run Doctor | Check your environment: Java version, JBang, Maven, Docker, port conflicts, disk space. +| Reset Stats | Reset all statistics and metrics for the selected integration. +| Stop All | Stop running integrations and/or infrastructure services. +| Take Screenshot | Export the current screen as SVG, text, or ANSI art. +| Start/Stop Tape Recording | Record your session as a `.tape` file for demos. +|=== + +=== Sending Test Messages + +Select *Send Message* from the F2 menu (or press *F2* then choose it): + +* *Choose the route* -- use left/right arrows to pick the target route +* *Enter the body* -- type the message body, or use `file:path/to/file` to load from a file +* *Add headers* -- press *+* to add headers as key=value pairs +* *Set exchange pattern* -- toggle between InOnly (fire-and-forget) and InOut (request/reply) +* Press *Enter* to send + +For InOut exchanges, the response is displayed below with status, elapsed time, response headers, +and body. Press *P* to toggle pretty-printing for JSON/XML responses. + +=== Doctor -* *tui_navigate* -- Switch tabs, select integrations, select routes in the topology -* *tui_send_keys* -- Send keystrokes to navigate like a human would -* *tui_filter* -- Apply text filters on tabs that support it +The Doctor checks your development environment and reports issues: -==== Act +* Java version (17+ required, 21+ recommended) +* Camel catalog availability +* JBang installation +* Maven repository connectivity +* Docker/Podman availability +* Common port conflicts (8080, 8443, 9090) +* Disk space in temp directory -* *tui_send_message* -- Send a test message to any Camel endpoint -* *tui_control* -- Start/stop/restart routes or the integration itself -* *tui_set_log_level* -- Change the runtime log level (DEBUG, INFO, WARN, etc.) +== Keyboard Shortcuts -==== Annotate +=== Global (All Tabs) -* *tui_locate* -- Find exact screen coordinates of text or diagram nodes -* *tui_draw_shape* -- Draw shapes on the screen: boxes, highlights, arrows, underlines, text labels -* *tui_draw* -- Draw individual characters at specific coordinates -* *tui_draw_clear* -- Clear all annotations -* *tui_show_caption* -- Display a text message with typewriter animation +[cols="2,5",options="header"] +|=== +| Key | Action + +| *1* - *0* | Jump to tab by number +| *Tab* / *Shift+Tab* | Next / previous tab +| *F1* | Context-sensitive help (toggle) +| *F2* | Actions menu +| *F3* | Switch between integrations (when multiple running) +| *Shift+F5* | Take screenshot +| *Ctrl+R* | Start/stop tape recording +| *Ctrl+C* / *Q* | Quit +| *Esc* | Close popup / go back / return to Overview +|=== -==== Present +=== Diagram Tab -* *tui_action* -- Invoke actions (screenshot, tape recording, reset stats, etc.) -* *tui_tape_start* / *tui_tape_stop* -- Record interactions as a `.tape` file -* *tui_sleep* -- Pace demo sequences -* *tui_toggle_trace_display* -- Control which sections show in trace views +[cols="2,5",options="header"] +|=== +| Key | Action + +| *Arrow keys* | Navigate between route boxes (topology) or EIP nodes (drill-down) +| *Enter* | Drill down into selected route / jump to linked route +| *Esc* | Go back (previous route or topology) +| *t* | Jump to topology view +| *m* | Toggle metrics overlay +| *e* | Cycle external endpoints (off / edges / all) +| *n* | Toggle description labels +| *c* | View route source code +|=== -=== Example: AI-Assisted Debugging +=== Inspect Tab -With MCP connected, you can ask the AI agent natural-language questions like: +[cols="2,5",options="header"] +|=== +| Key | Action + +| *Up/Down* | Navigate between steps +| *b* / *h* / *p* / *v* | Toggle body / headers / properties / variables +| *w* | Toggle word wrap +| *g* | Toggle waterfall view +| *d* | Toggle diagram replay mode +| *n* | Toggle description labels +| *F5* | Refresh / clear traces +|=== -* _"What routes are failing and why?"_ -- The agent reads the errors tab, correlates with route statistics, and explains the failures. -* _"Show me the message flow for the last exchange"_ -- The agent reads the trace history and walks you through each processing step. -* _"Highlight the failing routes on the diagram"_ -- The agent locates the routes on the topology, draws red boxes around them, and annotates with failure counts. -* _"Send a test order to the API endpoint"_ -- The agent sends a message to `platform-http:/api/orders` and watches the result flow through the routes. +== AI Integration (MCP) -=== Drawing and Annotations +The TUI includes an embedded https://modelcontextprotocol.io/[MCP] (Model Context Protocol) +server that lets AI coding assistants interact with the dashboard. -The AI agent can annotate the TUI screen with visual overlays. This is useful for -highlighting areas of interest, pointing out problems, or creating annotated screenshots -for documentation. +The TUI is fully functional on its own -- AI integration is entirely optional. -The typical workflow is: +=== Why This Matters -1. *tui_locate* to find exact coordinates (by text search or diagram node ID) -2. *tui_draw_shape* to draw the annotation (box, highlight, arrow, text) +When an AI agent connects to the TUI via MCP, it gains the same level of visibility that you +have -- and can act on it. The agent can: -Available shapes: +* *Read everything* -- route topology, statistics, message traces, errors, logs, source files, + health checks, and JVM metrics +* *Navigate and control* -- switch tabs, select routes, start/stop routes, send test messages, + change log levels +* *Teach and present* -- the AI can control the TUI screen to walk you through concepts, + highlight areas of interest, draw annotations, and take screenshots. It can circle a failing + route, draw arrows between connected endpoints, and add explanatory text labels -- turning the + TUI into a live whiteboard for pair-programming +* *Self-troubleshoot* -- when something fails, the AI can autonomously inspect the error, + read the message trace, correlate with route statistics, and produce a diagnostic report + with annotated screenshots showing exactly where and why the failure occurred -* *box* -- Rectangle border around an area (e.g., highlight a route node) -* *highlight* -- Background color on existing text, like a marker pen -* *underline* -- Horizontal line under text -* *arrow-down/up/left/right* -- Directional arrows for pointing at elements -* *text* -- Text labels for explanations +=== Enabling MCP + +[source,bash] +---- +camel tui --mcp +---- + +This starts an MCP server on `localhost:8123` (configurable with `--mcp-port`). +The server is bound to `127.0.0.1` only -- it never listens on external interfaces. + +When MCP is active, the TUI footer shows the connection status. +Use *F2* -> _MCP Info_ to see server details and _MCP Log_ to view the tool call history. + +=== Connecting an AI Agent + +To connect Claude Code to the TUI, add the MCP server to your project configuration +(`.mcp.json` in your project root): + +[source,json] +---- +{ + "mcpServers": { + "camel-tui": { + "type": "url", + "url": "http://localhost:8123/mcp"; + } + } +} +---- + +=== What AI Agents Can Do -Multiple shapes can be composed using the `append` flag. Annotations can auto-dismiss -after a duration or stay until explicitly cleared. +The MCP server exposes tools organized by purpose: + +* *Observe* -- read the screen, get structured state, query tables/logs/errors/traces/topology/diagram/files +* *Navigate* -- switch tabs, select integrations, select routes, send keystrokes, apply filters +* *Act* -- send test messages to endpoints, start/stop/restart routes, change log levels +* *Annotate* -- locate text and diagram nodes by coordinates, draw shapes (boxes, highlights, + arrows, underlines, text labels), show captions with typewriter animation +* *Present* -- take screenshots, record tape sessions, control demo pacing + +=== Example Workflows + +* _"What routes are failing and why?"_ -- The agent reads the errors tab, correlates with + route statistics, steps through the failing exchange in the Inspect tab, and explains + the root cause with annotated screenshots. +* _"Show me how this message flows through the system"_ -- The agent navigates to the Inspect tab, + opens the diagram replay, steps through each processor, and highlights the path on the + topology while explaining what happens at each step. +* _"Highlight the bottleneck routes"_ -- The agent reads the route statistics, locates the + slowest routes on the diagram, draws red boxes around them, and adds labels with the + processing times. See xref:camel-jbang-mcp.adoc[Camel MCP Server] for more about MCP and AI integration with Camel.
