[CAMEL 21975] Jbang diagram command to visualize camel routes

[vignesh-manel]

Description

Added Playwright-based PNG export for camel diagram via hawtio and Jolokia

Target

• I checked that the commit is targeting the correct branch (Camel 4 uses the main branch)

Tracking

• If this is a large change, bug fix, or code improvement, I checked there is a JIRA issue filed for the change (usually before you start working on it).

Apache Camel coding standards and style

• I checked that each commit in the pull request has a meaningful subject line and body.

• I have run mvn clean install -DskipTests locally from root folder and I have committed all auto-generated changes.

[davsclaus]

Thanks for helping with jbang. Can you make this into its own plugin as this should not be in the core.

You can look at one of the existing pluigins such as the new validate
https://github.com/apache/camel/tree/main/dsl/camel-jbang/camel-jbang-plugin-validate

[orpiske]

Nice idea, I'm but I'm under the impression this would be better done as a plugin. Let's see what others think about it ...

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using build-all, build-dependents, skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[vignesh-manel]

@davsclaus @Croway @orpiske Refactored as plugin, please review

[Croway]

Nice @vignesh-manel , were you able to test everything locally? can you provide some commands and outputs?

[davsclaus]

there are changes to camel-launcher / camel-jbang run etc - that is of course a bit more worring since this plugin should not break existing behaviour.

And what web browsers and OS does this work on ? Is it only google chrome ?

[vignesh-manel]

Nice @vignesh-manel , were you able to test everything locally? can you provide some commands and outputs?

I tested with the jar locally using below command from camel-launcher directory, it requires a browser executable which is compatible with chromium

java -jar target/camel-launcher-4.19.0-SNAPSHOT.jar diagram ../camel-jbang-core/src/test/resources/hello.yaml --output=hello.png --playwright-browser-path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

if --output is not specified it will open the hawtio console, where the integration can be viewed
if --keep-running option is provided, the integration will keep running in the background
--name=hello can be provided to capture diagram of integration which is already running in the background
--route-id=xyz can be provided if a there are multiple routes to capture diagram of specific route

[vignesh-manel]

there are changes to camel-launcher / camel-jbang run etc - that is of course a bit more worring since this plugin should not break existing behaviour.

And what web browsers and OS does this work on ? Is it only google chrome ?

I tried to simplify the changes, right now any chromium based browser is supported, I have tested it only in MacOS

[davsclaus]

Nice @vignesh-manel , were you able to test everything locally? can you provide some commands and outputs?

I tested with the jar locally using below command from camel-launcher directory, it requires a browser executable which is compatible with chromium

java -jar target/camel-launcher-4.19.0-SNAPSHOT.jar diagram ../camel-jbang-core/src/test/resources/hello.yaml --output=hello.png --playwright-browser-path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

if --output is not specified it will open the hawtio console, where the integration can be viewed if --keep-running option is provided, the integration will keep running in the background --name=hello can be provided to capture diagram of integration which is already running in the background --route-id=xyz can be provided if a there are multiple routes to capture diagram of specific route

I think this information would be good to add to the documentation, with that little example so others better can understand how to use this feature

[davsclaus]

the diagram is a plugin you need to install first via camel plugin add diagram

also I think there is some code where we have a known list of plugins we ship so diagram should be added there also

[vignesh-manel]

added

[davsclaus]

A good idea is to add that actual long command you typed to run on your mac, as mac users need to point to that /Content/XXX or whatever inside those apps - so users would maybe struggle if they dont have a real working example to see

[vignesh-manel]

added

[gnodet]

Code Review

Great feature — visualizing Camel routes directly from camel CLI is very useful. Here's detailed feedback on the implementation:

Dead code

DiagramPage.java has several unused/empty methods:

• selectRoutesFolder() — private, never called
• waitForDiagramAssets() — private, never called
• prepareDiagramForScreenshot() — called from two places but has an empty body

These should be removed or connected to the call paths where they're intended.

LauncherHelper.normalizeJarPath() returns null — potential NPE

The new normalizeJarPath() returns null when the path doesn't contain .jar. Callers at lines 68 and 162 in getLauncherJarPath() previously returned a valid path string but now may return null if running from an exploded classpath directory. This is a behavioral regression that could cause NPEs downstream.

Duplicated Jolokia logic

JolokiaAttacher directly uses com.sun.tools.attach.VirtualMachine and reimplements PID-finding logic. The existing Jolokia command in camel-jbang-core already handles this with the proper Jolokia client abstractions and ProcessBaseCommand.findPids(). Consider reusing the existing code rather than duplicating it. If the plugin module can't depend on ProcessBaseCommand, consider extracting the shared logic into a utility.

Minimal test coverage

The 5 tests only cover basic parameter binding. There are no tests for:

• LauncherHelper.normalizeJarPath() — a utility with several branches now used in critical paths
• LauncherHelper.findJolokiaAgentJar() — filesystem scanning
• JolokiaAttacher — PID resolution, port finding, agent loading
• DiagramPngExporter — the core export workflow
• PluginHelper.scanLauncherForPlugins() — nested JAR scanning

At minimum, normalizeJarPath() needs unit tests since it's in shared core code affecting all JBang commands.

Playwright is a heavyweight dependency

Playwright (~50MB+ with browser binaries) is a compile-time dependency of the entire plugin module but only needed for --output PNG export. When bundled into the launcher fat JAR, it increases download size for all users. Consider making it a runtime dependency downloaded on demand (similar to how Hawtio downloads its dependencies via MavenDependencyDownloader).

Minor issues

• arity = "0..9" limits file arguments to 9 — other JBang commands use "0..*" for unlimited files. Is this intentional?
• new Random().nextLong() for log file naming can produce negative numbers and has a NOSONAR suppression. Files.createTempFile("diagram-run", ".log") would be cleaner.
• --openUrl uses camelCase while all other options use kebab-case (--keep-running, --route-id). Consider adding a kebab-case alias --open-url.
• HTTP 4xx treated as success in waitForEndpoint() — code >= 200 && code < 500 && code != 404 accepts 401/403/405 as "endpoint available." Should be documented.
• URLClassLoader leak in PluginHelper.scanLauncherForPlugins() — the comment explains the rationale but consider storing loaders for shutdown cleanup.
• JS code tightly coupled to Hawtio internals — diagram-scripts.js uses PatternFly v5 CSS classes and React Flow internals. Any Hawtio UI update could break this silently. Consider documenting which Hawtio version this was tested against.

Summary

Priority	Issue
High	Dead code (unused/empty methods in DiagramPage)
High	normalizeJarPath returns null — behavioral regression
High	Duplicated Jolokia attach logic
High	Minimal test coverage for shared code changes
Medium	Playwright heavyweight compile dependency
Medium	File arity limited to 9
Low	Random filenames, option naming, HTTP 4xx handling, classloader leak