[camel-kafka-connector] branch master updated: Added a simple troubleshooting guide

[ac...@apache.org]

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

acosentino pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-kafka-connector.git


The following commit(s) were added to refs/heads/master by this push:
     new 194cba2  Added a simple troubleshooting guide
     new a3ab0c2  Merge pull request #383 from orpiske/add-troubleshooting-doc
194cba2 is described below

commit 194cba208852829744e25a9689ee12c36384c791
Author: Otavio Rodolfo Piske <op...@redhat.com>
AuthorDate: Tue Aug 18 17:03:43 2020 +0200

    Added a simple troubleshooting guide
---
 docs/modules/ROOT/nav.adoc                   |  1 +
 docs/modules/ROOT/pages/index.adoc           |  1 +
 docs/modules/ROOT/pages/troubleshooting.adoc | 73 ++++++++++++++++++++++++++++
 3 files changed, 75 insertions(+)

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 9e70b94..9210be9 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -9,4 +9,5 @@
 ** xref:getting-started-with-packages.adoc[Packages documentation]
 * xref:connectors.adoc[Connectors list]
 * xref:camel-compatibility-matrix.adoc[Apache Camel compatibility matrix]
+* xref:troubleshooting.adoc[Troubleshooting]
 * xref:contributing.adoc[Contributing]
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index 7600eaf..bf9eb8e 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -12,4 +12,5 @@
 ** xref:getting-started-with-packages.adoc[Packages documentation]
 * xref:connectors.adoc[Connectors list]
 * xref:camel-compatibility-matrix.adoc[Apache Camel compatibility matrix]
+* xref:troubleshooting.adoc[Troubleshooting]
 * xref:contributing.adoc[Contributing]
diff --git a/docs/modules/ROOT/pages/troubleshooting.adoc b/docs/modules/ROOT/pages/troubleshooting.adoc
new file mode 100644
index 0000000..c3e392f
--- /dev/null
+++ b/docs/modules/ROOT/pages/troubleshooting.adoc
@@ -0,0 +1,73 @@
+[[Troubleshooting-Troubleshooting]]
+= Troubleshooting the Camel Kafka Connector
+
+This page describes some common pitfalls when deploying the connectors.
+
+
+[[Troubleshooting-Contents]]
+== Table of Contents
+
+* <<connector-not-loaded,Kafka Connect does not load the Camel connector>>
+* <<missing-or-incorrect-converters,Missing or Incorrect Converters>>
+* <<missing-dependencies,Missing Dependencies>>
+* <<known-incompatibilities,Known Incompatibilities>>
+* <<known-limitations,Known Limitations>>
+
+[#connector-not-loaded]
+== Kafka Connect does not load the Camel connector
+
+If the Kafka Connect runtime is not loading the Camel connector, the cause could be an incorrect directory
+structure. There is a specific directory structure that needs to be followed when installing the connectors.
+They are meant to be installed in a subdirectory of the Kafka Connect https://kafka.apache.org/documentation/#plugin.path[plugin.path]
+and every connector should be within its own directory.
+
+For example, if you have set the value of `plugin.path` to `/camel-kafka-connectors/` then every connector should
+be within a directory inside it:
+
+* `/camel-kafka-connectors/camel-<component>-kafka-connector`
+
+It's possible to have multiple connectors in the `plugin.path`, therefore in a setup with both `amqp` and `hdfs`
+connectors, it would be possible to have a directory structure like this:
+
+* `/camel-kafka-connectors/camel-hdfs-kafka-connector`
+* `/camel-kafka-connectors/camel-amqp-kafka-connector`
+
+
+[#missing-or-incorrect-converters]
+== Missing or Incorrect Converters
+
+A common root cause for Kafka Connect failing to serialize or deserialize the data in transit is incorrect values
+for the https://kafka.apache.org/documentation/#key.converter[key.converter] or the
+https://kafka.apache.org/documentation/#value.converter[value.converter] (or both). There are usually verifiable
+in the logs by looking for `Caused by: org.apache.kafka.common.errors.SerializationException` or
+`Caused by: org.apache.kafka.connect.errors.DataException`.
+
+Here's one example with trying to exchange data using the AMQP connector without setting the `key.converter` and
+`value.converter` correctly:
+
+`Caused by: org.apache.kafka.connect.errors.DataException: JsonConverter with schemas.enable requires "schema" and "payload" fields and may not contain additional fields. If you are trying to deserialize plain JSON data, set schemas.enable=false in your converter configuration.`
+
+
+[#missing-dependencies]
+== Missing Dependencies
+
+When deploying the connector manually (ie.: without the assistance of tools such as Strimzi) you may need to
+make sure to provide the required runtime dependencies and their dependencies. Some notable examples are:
+
+* AMQP connector requires a JMS-compliant client (such as qpid-jms-client)
+* SJMS2 connector requires the client libraries for the protocol used to communicate with the broker (ie.:
+qpid-jms-client, activemq-client, artemis-jms-client, etc).
+* JDBC connector requires the JDBC client for the database
+
+
+[#known-incompatibilities]
+== Known Incompatibilities
+
+* Do not use activemq-all 5.16.0 or older with the SJMS2 connector: the activemq-all jar contains packages older
+versions of Camel that cause conflict when trying to run the connector. You may find very interesting errors such as
+`java.lang.NoSuchMethodError: org.apache.camel.main.Main.configure()Lorg/apache/camel/main/MainConfigurationProperties`
+when trying to do so.
+
+[#known-limitations]
+== Known Limitations
+