logstash-filter-ruby 3.1.6 → 3.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff2b98bf9fa5c8b404fb030defcdb9a1f9413b31f921d579bc42ee11e09d7fa9
-  data.tar.gz: d9b45322e9336e8cb827f298b0be7843f66468a6bd0b6592dc0fa435be6417b5
+  metadata.gz: 26f3d96124d72bdd663e9f2c384827d3b56734f296d1abfa143d68c67d67a252
+  data.tar.gz: 2e9fc5e99df96271fb68f08396670af1e7ba03a053f5590f77f7e5634bf6227c
 SHA512:
-  metadata.gz: 39c66c76bcfbbd84e2f171da1808565dbaede5ef9e7265aa1dca9123ab4f99f8db09c9de543ab9f6c4c232dbf4d674cc9e76697a1e95a349af0f362601cb3210
-  data.tar.gz: 8390d67f3024fc5a18a12109f0d7de2d3e38dfa8ac6e2f11a5b90b179e4ddd32f1bba9d67b1bb5f6703db483696c2573c226f36bd599a56d1ccba624af3b2886
+  metadata.gz: 168dfd8d904469861cf22aad44dfdb5accdb1a3b3b20e7dc238c02e15340fc667108a57935666a66d94fd0ca4b47fb535bdde4b38bc2011543ba6df47d93c5f5
+  data.tar.gz: 5198f9de1bff1f32e64b09877370d01fc77a2f462dc3fe803c212f73f264763db127e21fcc7d7eead8a1deb17353244fb9f4b2634893448fa5ee48d98f146488

data/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 3.1.7
+  - [DOC] Added docs to help people avoid concurrency issues (often caused by accidentally relying on shared state with global variables, constants, or unguarded overwriting of instance variables) [#58](https://github.com/logstash-plugins/logstash-filter-ruby/issues/58)
+
 ## 3.1.6
   - Add error log backtrace to inline scripts [#54](https://github.com/logstash-plugins/logstash-filter-ruby/pull/54)
 

data/docs/index.asciidoc

@@ -24,9 +24,12 @@ Execute ruby code. This filter accepts inline ruby code or a ruby file.
 The two options are mutually exclusive and have slightly different ways of working,
 which are described below.
 
+NOTE: This plugin's concurrency-safety depends on your code. Be sure to read up on <<plugins-{type}s-{plugin}-concurrency,how to avoid concurrency issues>>.
+
+[id="plugins-{type}s-{plugin}-using-inline-script"]
 ===== Inline ruby code
 
-To inline ruby in your filter, place all code in the `code` option. This code will be executed for every event the filter receives. You can also place ruby code in the `init` option - it will be executed only once during the plugin's register phase.
+To add inline ruby in your filter, place all code in the `code` option. This code will be executed for every event the filter receives. You can also place ruby code in the `init` option. It will be executed only once during the plugin's register phase.
 
 For example, to cancel 90% of events, you can do this:
 [source,ruby]
@@ -45,9 +48,12 @@ filter {
   }
 }
 
+NOTE: Defining methods in the <<plugins-{type}s-{plugin}-code,`code` option>> can significantly reduce throughput. Use the <<plugins-{type}s-{plugin}-init,`init` option>> instead.
+
+[id="plugins-{type}s-{plugin}-using-script-file"]
 ===== Using a Ruby script file
 
-As the inline code can become complex and hard to structure inside of a text string in `code`, it's then preferrable to place the Ruby code in a .rb file, using the `path` option.
+As the inline code can become complex and hard to structure inside of a text string in `code`, it's then preferable to place the Ruby code in a .rb file, using the `path` option.
 
 [source,ruby]
     filter {
@@ -132,6 +138,25 @@ Configuration OK
 [2017-10-13T13:44:29,887][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash
 ----
 
+[id="plugins-{type}s-{plugin}-concurrency"]
+==== Avoiding concurrency issues
+
+When events are flowing through a pipeline with multiple workers, a single shared instance of this filter may end up processing many events _simultaneously_.
+This means that your script needs to be written to avoid mutating shared state unless it is done in a thread-safe manner.
+
+In Ruby, the name of a variable determines its scope. The following guidance may help you avoid _accidentally_ mutating shared state:
+
+ * Freely use Local Variables, whose name begins with a lower-case letter or an underscore (`_`).
+ ** Local Variables are available only to the individual event being processed, and are automatically cleaned up.
+ * Exercise caution when _modifying_ Instance Variables, whose names begin with `@` followed by a lower-case letter or an underscore (`_`).
+ ** Instance Variables are shared between _all_ worker threads in this pipeline, which may be processing multiple events simultaneously.
+ ** It is safe to _set_ Instance Variables in a <<plugins-{type}s-{plugin}-using-script-file,script>>-defined `register` function or with <<plugins-{type}s-{plugin}-init>>, but they should not be modified while processing events unless safe-guarded by mutual exclusion.
+ ** Instance Variables are _not_ persisted across pipeline restarts or plugin crashes.
+ * _Avoid_ using variables whose scope is not limited to the plugin instance, as they can cause hard-to-debug problems that span beyond the individual plugin or pipeline:
+ ** Class Variables: begin with `@@`.
+ ** Global Variables: begin with a `$`.
+ ** Constants: begin with a capital letter.
+
 [id="plugins-{type}s-{plugin}-options"]
 ==== Ruby Filter Configuration Options
 

data/logstash-filter-ruby.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
 
   s.name            = 'logstash-filter-ruby'
-  s.version         = '3.1.6'
+  s.version         = '3.1.7'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "Executes arbitrary Ruby code"
   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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logstash-filter-ruby
 version: !ruby/object:Gem::Version
-  version: 3.1.6
+  version: 3.1.7
 platform: ruby
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-26 00:00:00.000000000 Z
+date: 2021-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement