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 文件的组合进行配置,这对于在多个输入和输出之间共享类似配置非常有用。JMS 插件也可以使用 JNDI 进行配置(如果需要)。
非 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 连接编辑
本节包含使用 Logstash 配置和 yaml 文件的组合连接到不使用 JNDI 的 JMS 提供程序的示例配置
非 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 连接编辑
本节包含使用 Logstash 配置和 yaml 文件的组合连接到使用 JNDI 的 JMS 提供程序的示例配置
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
edit
- 值类型为 布尔值
- 默认值为
false
接收 Oracle AQ 缓冲消息。在此模式下,不会接收持久性 Oracle AQ JMS 消息。仅适用于 Oracle AQ。
properties_target
edit
- 值类型为 字符串
-
默认值取决于是否启用了
ecs_compatibility
- ECS 兼容性禁用:此设置没有默认值
- ECS 兼容性已启用:`"[@metadata][input][jms][properties]"
如果 include_properties
设置,则添加 JMS 属性的字段名称。
require_jars
edit
- 值类型为 array
- 此设置没有默认值。
如果您不使用 yaml 配置,请使用工厂或 jndi_name。要为指定的 JMS 提供程序加载的 Jar 文件名的可选数组。通过使用此选项,无需在启动 Logstash 之前将所有 JMS 提供程序特定的 jar 文件放入 java CLASSPATH 中。
runner
edit
- 已弃用警告:此配置项已弃用,在将来的版本中可能不可用。
selector
edit
- 值类型为 字符串
- 此设置没有默认值。
JMS 消息选择器。与消息头或属性结合使用以筛选要处理的消息。只有与这里指定的查询匹配的消息才会被处理。请咨询您的 JMS 提供程序以了解正确的 JMS 消息选择器语法。
通用选项edit
以下配置选项受所有输入插件支持