[Docs] Add entry to troubleshooting guide (#38)

* [Docs] Add entry to troubleshooting guide

* [Docs] Incorporate code review comments

* Changelog entry and version bump

* [Docs] More code review suggestions implemented

Author: robbavey

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 3.1.2
+ - Docs: Added additional troubleshooting information [#38](https://github.com/logstash-plugins/logstash-input-jms/pull/38)
+
 ## 3.1.1
  - Added documentation for `factory_settings` configuration setting [#36](https://github.com/logstash-plugins/logstash-input-jms/pull/36)
 

docs/index.asciidoc

@@ -335,6 +335,37 @@ selector definitions must be double quoted in the Logstash configuration file, a
 single quoted, and numeric property values not quoted at all.
 
 
+===== Failed to create Event with MissingConverterException
+
+Messages from certain JMS providers may contain headers or properties that Logstash cannot interpret, which can lead to
+error messages such as:
+
+
+[source,txt]
+-----
+[2019-11-25T08:04:28,769][ERROR][logstash.inputs.jms      ] Failed to create event {:message=>Java::ComSolacesystemsJmsMessage::SolTextMessage: ...
+Attributes: {:jms_correlation_id=>"xxxx", :jms_delivery_mode_sym=>:non_persistent, :jms_destination=>"destination", :jms_expiration=>0, :jms_message_id=>"xxxxxx", :jms_priority=>0, :jms_redelivered=>false, :jms_reply_to=>#<Java::ComSolacesystemsJmsImpl::SolTopicImpl:0xdeadbeef>, :jms_timestamp=>1574669008862, :jms_type=>nil}
+Properties: nil, :exception=>org.logstash.MissingConverterException: Missing Converter handling for full class name=com.solacesystems.jms.impl.SolTopicImpl, simple name=SolTopicImpl, :backtrace=>["org.logstash.Valuefier.fallbackConvert(Valuefier.java:98)..."]}
+:exception=>org.logstash.MissingConverterException: Missing Converter handling for full class name=com.solacesystems.jms.impl.SolTopicImpl
+-----
+
+To get around this, use the `skip_headers` or `skip_properties` configuration setting to avoid attempting to process
+the offending header or property in the message.
+
+In the example shown above, this attribute is causing the
+`MissingConverterException`:
+
+`jms_reply_to=>#<Java::ComSolacesystemsJmsImpl::SolTopicImpl:0xdeadbeef>`
+
+
+To avoid this error, the configuration should include the following line:
+
+[source,ruby]
+-----
+skip_headers => ["jms_reply_to"]
+-----
+
+
 [id="plugins-{type}s-{plugin}-options"]
 ==== Jms Input Configuration Options
 

logstash-input-jms.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
 
   s.name            = 'logstash-input-jms'
-  s.version         = '3.1.1'
+  s.version         = '3.1.2'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "Reads events from a Jms Broker"
   s.description     = "This gem is a Logstash plugin required to be installed on top of the Logstash core pipeline using $LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program"