Jms 输入插件
编辑Jms 输入插件
编辑- 插件版本: v3.2.2
- 发布日期: 2022-06-13
- 更新日志
对于其他版本,请参阅 版本化插件文档。
获取帮助
编辑如果您对插件有任何疑问,请在 Discuss 论坛中发起主题讨论。对于错误或功能请求,请在 Github 中提交问题。有关 Elastic 支持的插件列表,请查阅 Elastic 支持矩阵。
描述
编辑从 Jms Broker 读取事件。支持 Jms 队列和主题。
有关 Jms 的更多信息,请参阅 https://javaee.github.io/tutorial/jms-concepts.html。有关使用的 Ruby Gem 的更多信息,请参阅 http://github.com/reidmorrison/jruby-jms。
JMS 配置可以完全在 Logstash 配置文件中完成,也可以混合使用 Logstash 配置文件和指定的 yaml 文件。不需要对连接工厂上的特定于实现的方法进行调用的简单配置可以在 Logstash 配置中完全指定,而更复杂的配置则应同时使用 yaml 文件和 Logstash 配置。
与 Elastic 通用架构 (ECS) 的兼容性
编辑JMS 数据是特定于应用程序的。字段的 ECS 兼容性取决于用例。该插件包含根据 ECS 兼容性模式 更改的合理默认值。当禁用 ECS 兼容性时,标头、属性和有效负载将定位到事件的根级别,以保持与该插件的旧版用法的兼容性。当针对 ECS 版本时,标头和属性会定位到 @metadata
子字段(除非在配置中另有指定),以避免与 ECS 字段发生冲突。请参阅 headers_target
、properties_target
和 target
。
仅使用 Logstash 配置的示例配置
编辑配置既可以完全在 Logstash 配置中配置,也可以通过 Logstash 配置和 yaml 文件的组合来配置,这对于跨多个输入和输出共享类似配置非常有用。如果需要,还可以使用 JNDI 配置 JMS 插件。
非 JNDI 连接的 Logstash 配置
编辑input { jms { broker_url => 'failover:(tcp://host1:61616,tcp://host2:61616)?initialReconnectDelay=100' destination => 'myqueue' factory => 'org.apache.activemq.ActiveMQConnectionFactory' pub_sub => false use_jms_timestamp => false # JMS provider credentials if needed username => 'username' password => 'secret' # JMS provider keystore and truststore details keystore => '/Users/logstash-user/security/keystore.jks' keystore_password => 'another_secret' truststore => '/Users/logstash-user/security/truststore.jks' truststore_password => 'yet_another_secret' # Parts of the JMS message to be included include_headers => false include_properties => false include_body => true # Message selector selector => "string_property = 'this' OR int_property < 3" # Connection factory specific settings factory_settings => { exclusive_consumer => true } # Jar Files to include require_jars => ['/usr/share/jms/activemq-all-5.15.9.jar'] } }
要连接到的代理的 URL。请查阅您的 JMS 提供程序文档以了解此处使用的确切语法,包括如何启用故障转移。 |
|
插件将从中侦听事件的主题或队列的名称。 |
|
用于与您的 JMS 提供程序创建连接的 Java 连接工厂的完整名称(包括包名称)。 |
|
确定事件源是队列还是主题,对于主题设置为 |
|
确定是否使用 JMSTimestamp 标头填充 |
|
连接到 JMS 提供程序时所需的凭据(如果需要)。 |
|
连接到 JMS 提供程序时所需的密钥库和信任库(如果需要)。 |
|
要包含在事件中的 JMS 消息的部分 - 标头、属性和消息正文可以包含在事件中或从事件中排除。 |
|
消息选择器:使用此选择器筛选要处理的消息。整个选择器查询应使用双引号括起来,字符串属性值应使用单引号括起来,数值属性值不应加引号。有关确切语法,请参阅 JMS 提供程序文档。 |
|
此处可以添加直接设置在 ConnectionFactory 对象上的其他设置。 |
|
JMS 提供程序所需的 jar 文件列表。路径应为 JMS 提供程序所需的所有 jar 文件的完全限定位置。此列表还可以包含依赖项 jar 文件以及 JMS 提供程序的特定 jar 文件。 |
JNDI 连接的 Logstash 配置
编辑input { jms { # Logstash Configuration Settings. include_headers => false include_properties => false include_body => true use_jms_timestamp => false destination => "myqueue" pub_sub => false # JNDI Settings jndi_name => /jms/cf/default jndi_context => { 'java.naming.factory.initial' => com.solacesystems.jndi.SolJNDIInitialContextFactory 'java.naming.security.principal' => solace-cloud-client@user 'java.naming.provider.url' => tcp://address.messaging.solace.cloud:20608 'java.naming.security.credentials' => verysecret } # Jar files to be imported require_jars=> ['/usr/share/jms/commons-lang-2.6.jar', '/usr/share/jms/sol-jms-10.5.0.jar', '/usr/share/jms/geronimo-jms_1.1_spec-1.1.1.jar', '/usr/share/jms/commons-lang-2.6.jar]' } }
使用 Logstash 配置和 Yaml 文件的示例配置
编辑非 JNDI 连接
编辑本节包含用于连接到不使用 JNDI 的 JMS 提供程序的示例配置,使用 Logstash 配置和 yaml 文件的组合
非 JNDI 连接的 Logstash 配置(对于包含 yaml 的配置)
编辑input { jms { # Logstash Configuration File Settings include_headers => false include_properties => false include_body => true use_jms_timestamp => false destination => "myqueue" pub_sub => false # JMS Provider credentials username => xxxx password => xxxx # Location of yaml file, and which section to use for configuration yaml_file => "~/jms.yml" yaml_section => "mybroker" } }
非 JNDI 连接的 Yaml 文件
编辑mybroker: :broker_url: 'ssl://127.0.0.1:61617' :factory: org.apache.activemq.ActiveMQConnectionFactory :exclusive_consumer: true :require_jars: - /usr/share/jms/activemq-all-5.15.9.jar - /usr/share/jms/log4j-1.2.17.jar
此代理定义的节名称。这应为 Logstash 配置文件中 |
|
代理的完整 URL。有关详细信息,请参阅您的 JMS 提供程序文档。 |
|
用于与您的 JMS 提供程序创建连接的 Java 连接工厂的完整名称(包括包名称)。 |
|
要与指定的连接工厂一起使用的特定于实现的配置参数。在 <3> 中。每个 JMS 提供程序都将有一套自己的参数可在此处使用。这些参数映射到提供的连接工厂上的 |
|
JMS 提供程序所需的 jar 文件列表。路径应为 JMS 提供程序所需的所有 jar 文件的完全限定位置。此列表还可以包含依赖项 jar 文件以及 JMS 提供程序的特定 jar 文件。 |
JNDI 连接
编辑本节包含用于连接到使用 JNDI 的 JMS 提供程序的示例配置,使用 Logstash 配置和 yaml 文件的组合
JNDI 连接的 Logstash 配置(对于包含 yaml 的配置)
编辑input { jms { # Logstash specific configuration settings include_headers => false include_properties => false include_body => true use_jms_timestamp => false destination => "myqueue" pub_sub => false # Location of yaml file, and which section to use for configuration yaml_file => "~/jms.yml" yaml_section => "mybroker" } }
JNDI 连接的 Yaml 文件
编辑solace: :jndi_name: /jms/cf/default :jndi_context: java.naming.factory.initial: com.solacesystems.jndi.SolJNDIInitialContextFactory java.naming.security.principal: solace-cloud-client@user java.naming.provider.url: tcp://address.messaging.solace.cloud:20608 java.naming.security.credentials: verysecret :require_jars: - /usr/share/jms/commons-lang-2.6.jar - /usr/share/jms/sol-jms-10.5.0.jar - /usr/share/jms/geronimo-jms_1.1_spec-1.1.1.jar - /usr/share/jms/commons-lang-2.6.jar
Jar 文件
编辑为了与 JMS 代理通信,插件必须加载每种客户端类型所需的 jar 文件。这可以在 yaml 文件中设置,或者如果不需要 yaml 文件,则可以在主配置中设置。 require_jars
设置应包含客户端所需的每个 jar 文件的完整路径。例如
Logstash 配置
编辑input { jms { : [snip] require_jars => ['/usr/share/jms/commons-lang-2.6.jar', '/usr/share/jms/sol-jms-10.5.0.jar', '/usr/share/jms/geronimo-jms_1.1_spec-1.1.1.jar', '/usr/share/jms/commons-lang-2.6.jar'] } }
故障排除
编辑本节包含用户在将此插件与他们的 JMS 提供程序集成时可能遇到的一些常见问题。
缺少 Jar 文件
编辑最常见的问题是缺少 jar 文件,这些文件可能是 JMS 供应商提供的 jar 文件,也可能是 JMS 供应商运行所需的 jar 文件。此问题可能会以不同的方式表现出来,具体取决于在何处发现缺少的 jar 文件。
示例日志输出
Failed to load JMS Connection, likely because a JMS Provider is not on the Logstash classpath or correctly specified by the plugin's `require_jars` directive {:exception=>"cannot load Java class javax.jms.DeliveryMode"
JMS Consumer Died {:exception=>"Java::JavaxNaming::NoInitialContextException", :exception_message=>"Cannot instantiate class:"
warning: thread "[main]<jms" terminated with exception (report_on_exception is true): java.lang.NoClassDefFoundError: org/apache/commons/lang/exception/NestableException
JMS Consumer Died {:exception=>"Java::JavaxJms::JMSException", :exception_message=>"io/netty/channel/epoll/Epoll", :root_cause=>{:exception=>"Java::JavaLang::NoClassDefFoundError", :exception_message=>"io/netty/channel/epoll/Epoll"}
如果出现任何这些问题,请检查 Logstash 配置或 yaml 配置文件中 require_jars
的列表。
设置系统属性
编辑许多 JMS 提供程序允许或期望设置系统属性以在使用 JMS 时配置某些属性,例如,Apache qpid JMS 客户端允许将连接工厂查找存储在那里,而 Solace JMS 客户端允许许多属性(例如连接重试次数)设置为系统属性。任何设置的系统属性都应在 Logstash jvm.options
文件中设置。
在同一个 Logstash 进程中使用多个 JMS 输入/输出
编辑如果在同一个 Logstash 进程中使用多个 JMS 消费者和生产者不受支持
- 任何消费者/生产者都需要不同的系统属性
- 任何消费者/生产者都需要不同的密钥库或信任库
消息选择器意外筛选掉所有消息
编辑不正确的消息选择器语法可能产生两种影响 - 要么语法不正确,JMS 提供程序的选择器解析器将抛出异常导致插件失败,要么语法将被接受,但消息将被静默丢弃 - 这可能发生在选择器定义中对字符串属性的引用不正确时。所有选择器定义都必须在 Logstash 配置文件中用双引号括起来,字符串属性值必须用单引号括起来,数值属性值则根本不加引号。
使用 MissingConverterException 无法创建事件
编辑来自某些 JMS 提供程序的消息可能包含 Logstash 无法解释的标头或属性,这可能导致出现以下错误消息
[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
要解决此问题,请使用 skip_headers
或 skip_properties
配置设置以避免尝试处理消息中违规的标头或属性。
在上面显示的示例中,此属性导致 MissingConverterException
jms_reply_to=>#<Java::ComSolacesystemsJmsImpl::SolTopicImpl:0xdeadbeef>
为避免此错误,配置应包含以下行
skip_headers => ["jms_reply_to"]
Jms 输入配置选项
编辑此插件支持以下配置选项以及稍后描述的 通用选项。
设置 | 输入类型 | 必需 |
---|---|---|
否 |
||
是 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
有效的系统文件路径 |
否 |
|
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
已弃用 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
否 |
||
有效的系统文件路径 |
否 |
|
否 |
||
否 |
||
否 |
||
否 |
||
否 |
另请参见 通用选项,以获取所有输入插件支持的选项列表。
destination
编辑- 这是一个必需设置。
- 值类型为 字符串
- 此设置没有默认值。
要使用的目标队列或主题的名称。
如果目标设置似乎无法正常工作,请尝试以下格式:<JMS 模块名称>!<JMS 队列名称>
。
durable_subscriber
编辑- 值类型为 布尔值
- 默认值为
false
- 需要
pub_sub
为 true
将此值设置为 true
将使对主题的订阅“持久”,从而允许在 Logstash 未运行时到达指定主题的消息仍然被读取。如果不设置此值,则在 Logstash 未积极监听时发送到主题的任何消息都将丢失。持久订阅指定一个唯一的标识,该标识由主题(destination
)、客户端 ID(durable_subscriber_client_id
)和订阅者名称(durable_subscriber_subscriber_name
)组成。有关这些设置的任何其他要求/限制,请参阅您的 JMS 提供程序文档。
- 请注意,持久订阅一次只能有一个活动订阅者。
- 请注意,仅当
pub_sub
设置为 true 时才允许使用此设置,否则将生成配置错误
durable_subscriber_client_id
编辑- 值类型为 字符串
- 如果设置了
durable_subscriber
,则此设置的默认值为 Logstash,否则此设置无效
这表示持久订阅的客户端 ID 的值,仅在 durable_subscriber
设置为 true
时使用。
durable_subscriber_name
编辑- 值类型为 字符串
- 如果设置了
durable_subscriber
,则此设置的默认值将与destination
设置相同,否则此设置无效。
这表示持久订阅的订阅者名称的值,仅在 durable_subscriber
设置为 true
时使用。有关此设置的约束和要求,请参阅您的 JMS 提供程序文档。
ecs_compatibility
编辑- 值类型为 字符串
-
支持的值为
-
disabled
:不使用与 ECS 兼容的字段名称(字段可能设置在事件的根目录下) -
v1
、v8
:避免可能与 Elastic Common Schema 冲突的字段名称(例如,JMS 特定属性)
-
-
默认值取决于正在运行的 Logstash 版本
- 当 Logstash 提供
pipeline.ecs_compatibility
设置时,其值将用作默认值 - 否则,默认值为
disabled
。
- 当 Logstash 提供
控制此插件与 Elastic Common Schema (ECS) 的兼容性。此设置的值会影响 headers_target
和 properties_target
的默认值。
factory_settings
编辑- 值类型为 哈希
- 此设置没有默认值。
要在 JMS 提供程序的连接工厂上设置的实现特定配置值的哈希。每个 JMS 提供程序都将有一组自己的参数可在此处使用。这些参数映射到提供的连接工厂上的 set
方法,并且可以使用蛇形或驼峰形表示法提供。例如,包含 exclusive_consumer => true
的哈希将调用提供的连接工厂上的 setExclusiveConsumer(true)
。有关实现特定详细信息,请参阅您的 JMS 提供程序文档。
headers_target
编辑- 值类型为 字符串
-
默认值取决于是否启用了
ecs_compatibility
- ECS 兼容性已禁用:此设置没有默认值
- ECS 兼容性已启用:`"[@metadata][input][jms][headers]"
如果设置了 include_headers
,则 JMS 标头将在其下添加的字段的名称。
include_body
编辑- 值类型为 布尔值
- 默认值为
true
在事件中包含 JMS 消息正文。支持 TextMessage、MapMessage 和 BytesMessage。
如果 JMS 消息是 TextMessage 或 BytesMessage,则该值将位于事件的“message”字段中。如果 JMS 消息是 MapMessage,则默认情况下,所有键/值对都将添加到事件的顶层。为了避免污染顶层命名空间,在接收 MapMessage 时,请使用 target
。
不支持 StreamMessage 和 ObjectMessage。
include_headers
编辑- 值类型为 布尔值
- 默认值为
true
JMS 消息包含三个部分
- 消息标头(必需)
- 消息属性(可选)
- 消息正文(可选)
您可以告诉输入插件哪些部分应包含在 Logstash 生成的事件中。
在事件中包含标准 JMS 消息标头字段值。示例标头
{ "jms_message_id" => "ID:amqhost-39547-1636977297920-71:1:1:1:1", "jms_timestamp" => 1636977329102, "jms_expiration" => 0, "jms_delivery_mode" => "persistent", "jms_redelivered" => false, "jms_destination" => "topic://41ad5342149901ad", "jms_priority" => 4, "jms_type" => "sample", "jms_correlation_id" => "28d975cb-14ff-4285-841e-05ef1e0a7ab2" }
jndi_context
编辑- 值类型为 哈希
- 此设置没有默认值。
仅在使用 JNDI 查找时使用。用于确定如何在使用 JNDI 时连接 JMS 消息代理的键值对。有关此处使用的正确值,请参阅您的 JMS 提供程序文档。
oracle_aq_buffered_messages
编辑- 值类型为 布尔值
- 默认值为
false
接收 Oracle AQ 缓冲消息。在此模式下,不会接收持久 Oracle AQ JMS 消息。仅适用于 Oracle AQ
properties_target
编辑- 值类型为 字符串
-
默认值取决于是否启用了
ecs_compatibility
- ECS 兼容性已禁用:此设置没有默认值
- ECS 兼容性已启用:`"[@metadata][input][jms][properties]"
如果设置了 include_properties
,则 JMS 属性将在其下添加的字段的名称。
require_jars
编辑- 值类型为 数组
- 此设置没有默认值。
如果不使用 yaml 配置,请使用 factory 或 jndi_name。要为指定的 JMS 提供程序加载的 Jar 文件名的可选数组。通过使用此选项,无需在启动 Logstash 之前将所有 JMS 提供程序特定的 jar 文件放入 java CLASSPATH。
runner
编辑- 已弃用警告:此配置项已弃用,在将来的版本中可能不可用。
selector
编辑- 值类型为 字符串
- 此设置没有默认值。
JMS 消息选择器。与消息标头或属性结合使用以筛选要处理的消息。只有与此处指定的查询匹配的消息才会被处理。有关正确的 JMS 消息选择器语法,请咨询您的 JMS 提供程序。