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 Common Schema (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'] } }
要连接的 Broker 的 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
此 Broker 定义的节名称。这应该是 Logstash 配置文件中 |
|
Broker 的完整 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 Broker 通信,插件必须加载每种客户端类型所需的 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 文件,这些 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
方法,并且可以以snake或camel大小写形式提供。例如,包含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配置,请使用工厂或jndi_name。要为指定的JMS提供程序加载的可选Jar文件名数组。通过使用此选项,不必在启动Logstash之前将所有JMS提供程序特定的jar文件放入Java CLASSPATH中。
runner
编辑- 已弃用警告:此配置项已弃用,可能在以后的版本中不可用。
selector
编辑- 值类型为字符串
- 此设置没有默认值。
JMS消息选择器。与消息标头或属性结合使用,以筛选要处理的消息。仅处理与此处指定的查询匹配的消息。有关正确的JMS消息选择器语法,请咨询您的JMS提供程序。
通用选项
编辑所有输入插件都支持这些配置选项
codec
编辑- 值类型为 编解码器
- 默认值为
"plain"
用于输入数据的编解码器。输入编解码器是一种方便的方法,可以在数据进入输入之前对其进行解码,而无需在 Logstash 管道中设置单独的过滤器。