logstash-filter-fingerprint 3.0.2 → 3.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 68305ab23e7ade962dc59f91089afb608fe5b686
-  data.tar.gz: 7a8549e0f212d6c14a2a44d335a558abeb03c47c
+  metadata.gz: b3889ab595d8eca1bc3da12afedeccf70c57370d
+  data.tar.gz: e6b9ac28e026a168dc2b59ca51cd9df3af7369b6
 SHA512:
-  metadata.gz: d8ef30f82e078b8682cb2a601e2875b74307293eb699301cf7205a3f02f2acf262a099902c218513c67e7662c6dfae46556604a5b40d3c0d0c4bc36074ea0958
-  data.tar.gz: 32de85113911a91161e6cd5cbe72a1ae026b876a0f199601962eb82726e4806d745354956c896855c665df3d0a37fa79c1f857cd7981a8e92bdef7fbd9612cf6
+  metadata.gz: 8ca3a82727adf9af513c611fe06151e22c251043a222bde4bb699e889186bf04631b27780ba75ad83daa9682a615a5d9fed40b543e35e0e82a4481e5c5d8edc1
+  data.tar.gz: 0a8f6d898e1d2109e968284c7c26c5feadc6bf66d8d61b64d6a25634ae1cd78af01002da0c4001f0edd83bdaec334983490f30edbabe2ea35eafa1f647532d6f

data/CHANGELOG.md

@@ -1,19 +1,26 @@
+## 3.0.3
+  - improve documentation and register exception messaging
+
 ## 3.0.2
   - Relax constraint on logstash-core-plugin-api to >= 1.60 <= 2.99
 
 ## 3.0.1
-  - Republish all the gems under jruby.
+ - internal: Republish all the gems under jruby.
+
 ## 3.0.0
-  - Update the plugin to the version 2.0 of the plugin api, this change is required for Logstash 5.0 compatibility. See https://github.com/elastic/logstash/issues/5141
-# 2.0.5
-  - Depend on logstash-core-plugin-api instead of logstash-core, removing the need to mass update plugins on major releases of logstash
-# 2.0.4
-  - New dependency requirements for logstash-core for the 5.0 release
+ - internal,deps: Update the plugin to the version 2.0 of the plugin api, this change is required for Logstash 5.0 compatibility. See https://github.com/elastic/logstash/issues/5141
+
+## 2.0.5
+ - internal,deps: Depend on logstash-core-plugin-api instead of logstash-core, removing the need to mass update plugins on major releases of logstash
+
+## 2.0.4
+ - internal,deps: New dependency requirements for logstash-core for the 5.0 release
+
 ## 2.0.3
- - Eager loading of libraries, optimizations and cleanups https://github.com/logstash-plugins/logstash-filter-fingerprint/pull/10
+ - internal,cleanup: Eager loading of libraries, optimizations and cleanups https://github.com/logstash-plugins/logstash-filter-fingerprint/pull/10
 
 ## 2.0.0
- - Plugins were updated to follow the new shutdown semantic, this mainly allows Logstash to instruct input plugins to terminate gracefully,
+ - internal: Plugins were updated to follow the new shutdown semantic, this mainly allows Logstash to instruct input plugins to terminate gracefully,
    instead of using Thread.raise on the plugins' threads. Ref: https://github.com/elastic/logstash/pull/3895
- - Dependency on logstash-core update to 2.0
+ - internal,deps: Dependency on logstash-core update to 2.0
 

data/lib/logstash/filters/fingerprint.rb

@@ -7,30 +7,67 @@ require "ipaddr"
 require "murmurhash3"
 require "securerandom"
 
-#  Fingerprint fields using by replacing values with a consistent hash.
+# Create consistent hashes (fingerprints) of one or more fields and store
+# the result in a new field.
+#
+# This can e.g. be used to create consistent document ids when inserting
+# events into Elasticsearch, allowing events in Logstash to cause existing
+# documents to be updated rather than new documents to be created.
+#
+# NOTE: When using any method other than 'UUID', 'PUNCTUATION' or 'MURMUR3'
+# you must set the key, otherwise the plugin will raise an exception
+#
+# NOTE: When the `target` option is set to `UUID` the result won't be
+# a consistent hash but a random
+# https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID].
+# To generate UUIDs, prefer the <<plugins-filters-uuid,uuid filter>>.
 class LogStash::Filters::Fingerprint < LogStash::Filters::Base
   config_name "fingerprint"
 
-  # Source field(s)
+  # The name(s) of the source field(s) whose contents will be used
+  # to create the fingerprint. If an array is given, see the
+  # `concatenate_sources` option.
   config :source, :validate => :array, :default => 'message'
 
-  # Target field.
-  # will overwrite current value of a field if it exists.
+  # The name of the field where the generated fingerprint will be stored.
+  # Any current contents of that field will be overwritten.
   config :target, :validate => :string, :default => 'fingerprint'
 
-  # When used with `IPV4_NETWORK` method fill in the subnet prefix length
-  # Not required for `MURMUR3` or `UUID` methods
-  # With other methods fill in the `HMAC` key
+  # When used with the `IPV4_NETWORK` method fill in the subnet prefix length.
+  # Not required for `MURMUR3`, `PUNCTUATION` or `UUID` methods.
+  # With other methods fill in the HMAC key.
   config :key, :validate => :string
 
-  # When set to 'true', SHA1', 'SHA256', 'SHA384', 'SHA512' and 'MD5' fingerprint methods will be returned
-  # base64 encoded rather than hex encoded.
+  # When set to `true`, the `SHA1`, `SHA256`, `SHA384`, `SHA512` and `MD5` fingerprint methods will produce
+  # base64 encoded rather than hex encoded strings.
   config :base64encode, :validate => :boolean, :default => false
 
-  # Fingerprint method
+  # The fingerprint method to use.
+  #
+  # If set to `SHA1`, `SHA256`, `SHA384`, `SHA512`, or `MD5` the
+  # cryptographic keyed-hash function with the same name will be used to
+  # generate the fingerprint. If set to `MURMUR3` the non-cryptographic
+  # MurmurHash function will be used.
+  #
+  # If set to `IPV4_NETWORK` the input data needs to be a IPv4 address and
+  # the hash value will be the masked-out address using the number of bits
+  # specified in the `key` option. For example, with "1.2.3.4" as the input
+  # and `key` set to 16, the hash becomes "1.2.0.0".
+  #
+  # If set to `PUNCTUATION`, all non-punctuation characters will be removed
+  # from the input string.
+  #
+  # If set to `UUID`, a
+  # https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID] will
+  # be generated. The result will be random and thus not a consistent hash.
   config :method, :validate => ['SHA1', 'SHA256', 'SHA384', 'SHA512', 'MD5', "MURMUR3", "IPV4_NETWORK", "UUID", "PUNCTUATION"], :required => true, :default => 'SHA1'
 
-  # When set to `true`, we concatenate the values of all fields into 1 string like the old checksum filter.
+  # When set to `true` and `method` isn't `UUID` or `PUNCTUATION`, the
+  # plugin concatenates the names and values of all fields given in the
+  # `source` option into one string (like the old checksum filter) before
+  # doing the fingerprint computation. If `false` and multiple source
+  # fields are given, the target field will be an array with fingerprints
+  # of the source fields given.
   config :concatenate_sources, :validate => :boolean, :default => false
 
   def register
@@ -42,7 +79,7 @@ class LogStash::Filters::Fingerprint < LogStash::Filters::Base
     when :IPV4_NETWORK
       if @key.nil?
         raise LogStash::ConfigurationError, I18n.t(
-          "logstash.agent.configuration.invalid_plugin_register",
+          "logstash.runner.configuration.invalid_plugin_register",
           :plugin => "filter",
           :type => "fingerprint",
           :error => "Key value is empty. please fill in a subnet prefix length"
@@ -58,7 +95,7 @@ class LogStash::Filters::Fingerprint < LogStash::Filters::Base
     else
       if @key.nil?
         raise LogStash::ConfigurationError, I18n.t(
-          "logstash.agent.configuration.invalid_plugin_register",
+          "logstash.runner.configuration.invalid_plugin_register",
           :plugin => "filter",
           :type => "fingerprint",
           :error => "Key value is empty. Please fill in an encryption key"
@@ -101,6 +138,7 @@ class LogStash::Filters::Fingerprint < LogStash::Filters::Base
         end
       end
     end
+    filter_matched(event)
   end
 
   private

data/logstash-filter-fingerprint.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
 
   s.name            = 'logstash-filter-fingerprint'
-  s.version         = '3.0.2'
+  s.version         = '3.0.3'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "Fingerprint fields using by replacing values with a consistent hash."
   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"

data/spec/filters/fingerprint_spec.rb

@@ -286,4 +286,22 @@ describe LogStash::Filters::Fingerprint do
     end
   end
 
+  describe "execution triggers addition of fields and tags" do
+    config <<-CONFIG
+      filter {
+        fingerprint {
+          source => 'field1'
+          method => 'PUNCTUATION'
+          add_field => { 'myfield' => 'myvalue' }
+          add_tag => ['mytag']
+        }
+      }
+    CONFIG
+
+    sample("field1" => "Hello, World!") do
+      insist { subject.get("myfield") } == "myvalue"
+      insist { subject.get("tags") } == ["mytag"]
+    end
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logstash-filter-fingerprint
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.0.3
 platform: ruby
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2016-07-14 00:00:00.000000000 Z
+date: 2017-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
@@ -95,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project:
-rubygems_version: 2.6.3
+rubygems_version: 2.4.8
 signing_key:
 specification_version: 4
 summary: Fingerprint fields using by replacing values with a consistent hash.