You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by nf...@apache.org on 2020/10/19 12:06:27 UTC
[camel-k] 02/02: Add doc about kamel debug command
This is an automated email from the ASF dual-hosted git repository.
nferraro pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit a272bb42b242784394a06b3df41da8d0b269975e
Author: nicolaferraro <ni...@gmail.com>
AuthorDate: Thu Oct 15 23:09:13 2020 +0200
Add doc about kamel debug command
---
.../assets/images/debugging/remote-debugger.png | Bin 0 -> 70273 bytes
docs/modules/ROOT/nav-end.adoc | 15 ++++++-
docs/modules/ROOT/nav.adoc | 11 -----
docs/modules/ROOT/pages/cli/cli.adoc | 4 ++
.../ROOT/pages/troubleshooting/debugging.adoc | 50 +++++++++++++++++++++
.../known-issues.adoc} | 4 +-
6 files changed, 70 insertions(+), 14 deletions(-)
diff --git a/docs/modules/ROOT/assets/images/debugging/remote-debugger.png b/docs/modules/ROOT/assets/images/debugging/remote-debugger.png
new file mode 100644
index 0000000..3accca3
Binary files /dev/null and b/docs/modules/ROOT/assets/images/debugging/remote-debugger.png differ
diff --git a/docs/modules/ROOT/nav-end.adoc b/docs/modules/ROOT/nav-end.adoc
index 1e8f12e..11d29c4 100644
--- a/docs/modules/ROOT/nav-end.adoc
+++ b/docs/modules/ROOT/nav-end.adoc
@@ -1,3 +1,16 @@
-* xref:troubleshooting.adoc[Troubleshooting]
+* Troubleshooting
+** xref:troubleshooting/debugging.adoc[Debugging]
+** xref:troubleshooting/known-issues.adoc[Known Issues]
+* xref:kamelets/kamelets.adoc[Kamelets]
+* xref:architecture/architecture.adoc[Architecture]
+** xref:architecture/operator.adoc[Operator]
+*** xref:architecture/cr/integration-platform.adoc[IntegrationPlatform]
+*** xref:architecture/cr/integration.adoc[Integration]
+*** xref:architecture/cr/integration-kit.adoc[IntegrationKit]
+*** xref:architecture/cr/build.adoc[Build]
+*** xref:architecture/cr/camel-catalog.adoc[CamelCatalog]
+** xref:architecture/runtime.adoc[Runtime]
+** xref:architecture/traits.adoc[Traits]
+** xref:architecture/sources.adoc[Sources]
* xref:uninstalling.adoc[Uninstalling]
* xref:developers.adoc[Contributing]
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 6953c36..ef1ff50 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -53,14 +53,3 @@
** xref:traits:service.adoc[Service]
** xref:traits:tracing.adoc[Tracing]
// End of autogenerated code - DO NOT EDIT! (trait-nav)
-* xref:kamelets/kamelets.adoc[Kamelets]
-* xref:architecture/architecture.adoc[Architecture]
-** xref:architecture/operator.adoc[Operator]
-*** xref:architecture/cr/integration-platform.adoc[IntegrationPlatform]
-*** xref:architecture/cr/integration.adoc[Integration]
-*** xref:architecture/cr/integration-kit.adoc[IntegrationKit]
-*** xref:architecture/cr/build.adoc[Build]
-*** xref:architecture/cr/camel-catalog.adoc[CamelCatalog]
-** xref:architecture/runtime.adoc[Runtime]
-** xref:architecture/traits.adoc[Traits]
-** xref:architecture/sources.adoc[Sources]
diff --git a/docs/modules/ROOT/pages/cli/cli.adoc b/docs/modules/ROOT/pages/cli/cli.adoc
index b90044c..26d220b 100644
--- a/docs/modules/ROOT/pages/cli/cli.adoc
+++ b/docs/modules/ROOT/pages/cli/cli.adoc
@@ -28,6 +28,10 @@ Some of the most used commands are:
|Run an integration on Kubernetes
|`kamel run Routes.java`
+|debug
+|Debug a remote integration using a local debugger
+|`kamel debug myintegration`
+
|get
|Get integrations deployed on Kubernetes
|`kamel get`
diff --git a/docs/modules/ROOT/pages/troubleshooting/debugging.adoc b/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
new file mode 100644
index 0000000..be4bfeb
--- /dev/null
+++ b/docs/modules/ROOT/pages/troubleshooting/debugging.adoc
@@ -0,0 +1,50 @@
+= Debugging Camel K Integrations
+
+Sometimes integrations can fail or behave unexpectedly for unknown reasons and a developer needs to investigate the cause of such behavior.
+Attaching a debugger to an integration is a common way to start the investigation.
+
+Even if Camel K integrations run on a Kubernetes cluster, it's very easy to attach a debugger to the remote integration using the CLI.
+
+Suppose you just launched an integration using the following command:
+
+[source,shell]
+----
+kamel run examples/Sample.java
+----
+
+An integration named `sample` should be running in the cluster.
+You can use the `kamel debug` command to put it in "debug mode".
+
+[source,shell]
+----
+kamel debug sample
+----
+
+A possible output that you may find is the following:
+
+[source,shell]
+----
+$ kamel debug sample
+Enabling debug mode on integration "sample"...
+[1] Monitoring pod sample-8455c8b985-5cxvc
+[1] exec java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 -cp ./resources:[..omitted..] io.quarkus.runner.GeneratedMain
+[1] Listening for transport dt_socket at address: 5005
+Forwarding from 127.0.0.1:5005 -> 5005
+Forwarding from [::1]:5005 -> 5005
+----
+
+As you can see in the logs, the CLI has configured the integration in debug mode (see option `-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005`)
+and started forwarding the local port 5005 on the workstation machine (local port can be changed using the `--port` option) to the container port 5005, where the JVM is waiting for a debugger.
+
+The JVM is suspended and waits for a debugger to attach by default: this behavior can be turned off using the `--suspend=false` option.
+
+Last thing to do is, with your IDE opened on the **integration file (if using Java, Groovy or Kotlin), the Apache Camel project or the Camel K Runtime project**,
+to start a remote debugger on `localhost:5005`.
+
+The following picture shows the configuration of a remote debugger in IntelliJ Idea.
+
+image::debugging/remote-debugger.png[Configuration of the remote debugger in IntelliJ Idea]
+
+Once you configure a debugger, you can **add breakpoints** to various part of the code, then connect the debugger to trigger the JVM startup.
+
+When the debugging session is finished, hitting *ctrl+c* on the terminal where the kamel CLI is running will restore the integration to its original status.
diff --git a/docs/modules/ROOT/pages/troubleshooting.adoc b/docs/modules/ROOT/pages/troubleshooting/known-issues.adoc
similarity index 96%
rename from docs/modules/ROOT/pages/troubleshooting.adoc
rename to docs/modules/ROOT/pages/troubleshooting/known-issues.adoc
index c360cfb..846ec5f 100644
--- a/docs/modules/ROOT/pages/troubleshooting.adoc
+++ b/docs/modules/ROOT/pages/troubleshooting/known-issues.adoc
@@ -1,5 +1,5 @@
-[[troubleshooting]]
-= Troubleshooting
+[[known-issues]]
+= Known Issues
== `Error during unshare(CLONE_NEWUSER): Invalid argument`