CAMEL-24003: Add heap dump command to CLI, TUI, and MCP

[davsclaus]

Summary

Claude Code on behalf of davsclaus

• Add camel cmd heap-dump CLI command to write .hprof heap dump files from a running Camel integration for deep memory analysis with tools like Eclipse MAT or VisualVM
• Add HeapDumpDevConsole in camel-console as the server-side implementation using HotSpotDiagnosticMXBean
• Wire the heap-dump action in LocalCliConnector to bridge CLI/TUI requests to the dev console
• Add heap dump support to TUI Memory and MemoryLeak tabs via h key shortcut
• Register write_heap_dump AI tool and camel_runtime_heap_dump MCP tool
• Add documentation page for the new command

Test plan

• Run camel cmd heap-dump against a running integration and verify .hprof file is created
• Run camel cmd heap-dump --dump-name=test --live=false and verify options work
• Open TUI Memory tab, press h, verify heap dump is written and notification appears
• Open TUI MemoryLeak tab, press h, verify heap dump is written and notification appears
• Verify MCP tool camel_runtime_heap_dump works via MCP client

🤖 Generated with Claude Code

[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 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.

[gnodet]

Review: CAMEL-24003 - Add heap dump command to CLI, TUI, and MCP

Nice feature addition. The implementation is well-structured and follows the established patterns for dev consoles, CLI commands, TUI integration, and MCP/AI tool registration. The layered approach (dev console -> CLI connector -> jbang command / TUI / MCP) is consistent with how heap-histogram, memory-leak, and other diagnostic features work.

A few items worth discussing:

Findings

1. [Medium] Direct compile-time dependency on com.sun.management.HotSpotDiagnosticMXBean (HeapDumpDevConsole.java)

The existing HeapHistogramDevConsole avoids a compile-time dependency on com.sun.management by using string-based MBean lookup (new ObjectName("com.sun.management:type=DiagnosticCommand")). The new HeapDumpDevConsole directly imports com.sun.management.HotSpotDiagnosticMXBean, which creates a hard compile-time dependency on HotSpot-internal API. This could cause NoClassDefFoundError on alternative JVMs (e.g., OpenJ9, GraalVM native image). Consider using the MXBean via ManagementFactory.getPlatformMBeanServer() and string-based invocation instead, or at minimum wrap the call so it degrades gracefully.

2. [Low] No input sanitization on dump file name (HeapDumpDevConsole.java)

The user-supplied name parameter is passed directly to bean.dumpHeap(name, live) after only appending .hprof. A value like ../../tmp/evil would write to an arbitrary path. Per Camel's security model, CLI/TUI users are trusted (they already have JVM-level access), so this is low severity. Still, stripping path separators or using Path.getFileName() would be a reasonable defensive measure.

3. [Low] Code duplication of triggerHeapDump() and notify() between MemoryTab and MemoryLeakTab

Both tabs contain nearly identical ~40-line triggerHeapDump() and notify() methods. The MemoryLeakTab version uses its existing startDaemonThread() helper, while MemoryTab creates the daemon thread inline. Consider extracting the shared logic to a utility (or a default method on a shared base) to avoid drift between the two copies.

4. [Low] No test coverage (project-wide)

No tests were added. While the existing HeapHistogramDevConsole also has no test, the project's CLAUDE.md states: "Every PR must include tests for new functionality or bug fixes." A basic unit test for the dev console (e.g., verifying JSON output shape, error propagation, default filename generation) would be straightforward and valuable.

5. [Info] MCP tool uses runtimeService.executeAction() directly instead of delegateToRegistry()

The adjacent camel_runtime_heap_histogram delegates via delegateToRegistry("get_heap_histogram", ...) while the new camel_runtime_heap_dump calls runtimeService.executeAction() directly. This is fine since heap dump needs custom parameter forwarding, but it is a pattern difference worth noting for consistency.

Summary

The feature is well-designed and the code is clean. The main item to consider is the direct com.sun.management import which introduces a HotSpot-specific compile dependency, unlike the existing heap histogram console which avoids it. The other findings are minor suggestions.

Scanner coverage

No static analysis tools (SonarCloud, SpotBugs, Error Prone) were executed as part of this review. This review does not replace those tools or specialized AI review tools like CodeRabbit.

Claude Code review on behalf of @gnodet

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

[davsclaus]

Thanks for the review @gnodet! All three inline findings have been addressed in 17b46ab:

1. MBeanServer — switched to string-based MBeanServer.invoke() via ObjectName("com.sun.management:type=HotSpotDiagnostic"), matching the HeapHistogramDevConsole pattern.
2. Path sanitization — added Path.of(name).getFileName().toString() to strip path separators.
3. Code duplication — extracted shared TuiHelper.triggerHeapDump() used by both MemoryTab and MemoryLeakTab.

On the remaining items:

4. Tests — agreed, the dev console modules in camel-console currently have no test infrastructure set up. The heap dump action requires a running JVM with the HotSpot MBean, which makes unit testing non-trivial (the dumpHeap call creates a real file). We can add basic tests for the filename sanitization and default-name logic in a follow-up.

5. MCP pattern — correct, the heap dump tool uses executeAction() directly because it needs to pass the name and live parameters through the action file protocol, which doesn't fit the delegateToRegistry() pattern used for simple get-style calls like heap histogram.

[github-actions]

🧪 CI tested the following changed modules:

• catalog/camel-catalog
• core/camel-console
• docs
• dsl/camel-cli-connector
• dsl/camel-jbang/camel-jbang-core
• dsl/camel-jbang/camel-jbang-mcp
• dsl/camel-jbang/camel-jbang-plugin-tui

---

🔬 Scalpel shadow comparison — Scalpel: 17 tested, 26 compile-only — current: 14 all tested

Maveniverse Scalpel detected 43 affected modules (current approach: 14).

⚠️ Modules only in Scalpel (29)

• apache-camel
• camel-allcomponents
• camel-catalog
• camel-catalog-console
• camel-catalog-lucene
• camel-catalog-maven
• camel-catalog-suggest
• camel-componentdsl
• camel-csimple-maven-plugin
• camel-endpointdsl
• camel-endpointdsl-support
• camel-itest
• camel-jbang-core
• camel-jbang-it
• camel-jbang-main
• camel-jbang-plugin-edit
• camel-jbang-plugin-generate
• camel-jbang-plugin-kubernetes
• camel-jbang-plugin-test
• camel-kamelet-main
• camel-launcher
• camel-report-maven-plugin
• camel-route-parser
• camel-yaml-dsl
• camel-yaml-dsl-deserializers
• camel-yaml-dsl-maven-plugin
• coverage
• docs
• dummy-component

Skip-tests mode would test 17 modules (7 direct + 10 downstream), skip tests for 26 (generated code, meta-modules)

Modules Scalpel would test (17)

• camel-catalog
• camel-cli-connector
• camel-cli-debug
• camel-console
• camel-core-all
• camel-diagram
• camel-jbang-console
• camel-jbang-core
• camel-jbang-mcp
• camel-jbang-plugin-mcp
• camel-jbang-plugin-route-parser
• camel-jbang-plugin-tui
• camel-jbang-plugin-validate
• camel-launcher-container
• camel-yaml-dsl-validator
• camel-yaml-dsl-validator-maven-plugin
• docs

Modules with tests skipped (26)

• apache-camel
• camel-allcomponents
• camel-catalog-console
• camel-catalog-lucene
• camel-catalog-maven
• camel-catalog-suggest
• camel-componentdsl
• camel-csimple-maven-plugin
• camel-endpointdsl
• camel-endpointdsl-support
• camel-itest
• camel-jbang-it
• camel-jbang-main
• camel-jbang-plugin-edit
• camel-jbang-plugin-generate
• camel-jbang-plugin-kubernetes
• camel-jbang-plugin-test
• camel-kamelet-main
• camel-launcher
• camel-report-maven-plugin
• camel-route-parser
• camel-yaml-dsl
• camel-yaml-dsl-deserializers
• camel-yaml-dsl-maven-plugin
• coverage
• dummy-component

ℹ️ Shadow mode — Scalpel observes but does not affect test execution. Learn more

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

• dsl/camel-jbang/camel-jbang-core: 1 test(s) disabled on GitHub Actions
• dsl/camel-jbang/camel-jbang-mcp: 1 test(s) disabled on GitHub Actions

💡 Manual integration tests recommended:

You modified dsl/camel-jbang/camel-jbang-core. The related integration tests in dsl/camel-jbang/camel-jbang-it are excluded from CI. Consider running them manually:

mvn verify -f dsl/camel-jbang/camel-jbang-it -Djbang-it-test

All tested modules (43 modules)

• Camel :: All Components Sync point
• Camel :: All Core Sync point
• Camel :: Assembly
• Camel :: Catalog :: CSimple Maven Plugin (deprecated)
• Camel :: Catalog :: Camel Catalog
• Camel :: Catalog :: Camel Report Maven Plugin
• Camel :: Catalog :: Camel Route Parser
• Camel :: Catalog :: Console
• Camel :: Catalog :: Dummy Component
• Camel :: Catalog :: Lucene (deprecated)
• Camel :: Catalog :: Maven
• Camel :: Catalog :: Suggest
• Camel :: Component DSL
• Camel :: Console
• Camel :: Coverage
• Camel :: DSL :: CLI Connector
• Camel :: DSL :: CLI Debug
• Camel :: Diagram
• Camel :: Docs
• Camel :: Endpoint DSL
• Camel :: Endpoint DSL :: Support
• Camel :: Integration Tests
• Camel :: JBang :: Console
• Camel :: JBang :: Core
• Camel :: JBang :: Integration tests
• Camel :: JBang :: MCP
• Camel :: JBang :: Main
• Camel :: JBang :: Plugin :: Edit
• Camel :: JBang :: Plugin :: Generate
• Camel :: JBang :: Plugin :: Kubernetes
• Camel :: JBang :: Plugin :: MCP
• Camel :: JBang :: Plugin :: Route Parser
• Camel :: JBang :: Plugin :: TUI
• Camel :: JBang :: Plugin :: Testing
• Camel :: JBang :: Plugin :: Validate
• Camel :: Kamelet Main
• Camel :: Launcher
• Camel :: Launcher :: Container
• Camel :: YAML DSL
• Camel :: YAML DSL :: Deserializers
• Camel :: YAML DSL :: Maven Plugins
• Camel :: YAML DSL :: Validator
• Camel :: YAML DSL :: Validator Maven Plugin

---

⚙️ View full build and test results