logstash-filter-translate 3.0.1 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a88523429ce3660b177179da29ca3817bbe0e4fd
-  data.tar.gz: 69e3b1a02058d4876b2b2e8a3104f5d346ed81d0
+  metadata.gz: f24578265064ba7eff335775a45c53a788f7ae95
+  data.tar.gz: 9f3402bad245470bcbe6fd96556710b3232205d6
 SHA512:
-  metadata.gz: 27cccb3185892156caac4e68bbbaa044837284505d33f0ca1b42b4a1b7bef478cda2927b86f03f4c1e62cafe6fc768050a9d8a2ce6a8bc11e70281ecb89eee57
-  data.tar.gz: 2938b6b48d5dc0159d9fe4236849b84bb8fcdf3878cf487324785881c503ca9d680b33375121cb6188ceb9fde515604e9e50f90b2d1d38ab3b65367ded3f788e
+  metadata.gz: 4fe297db163c1a1bf1b07ea3a0024539ca9e09fbd5fc728523ffb6fd79c59904ba16805a7cc38dfdf8ae74f31fe0ee05a2d563034daf81f353d14e06ee241a0e
+  data.tar.gz: 472bdd70f2a8290c4678ac1c03f544a127453ca008f85217600dc21b6e62cc13c0686bab3cc949d437ad1fece576ad19a776023b38c15876c4bd44862e914a47

data/Gemfile

@@ -1,2 +1,11 @@
 source 'https://rubygems.org'
-gemspec
+
+gemspec
+
+logstash_path = ENV["LOGSTASH_PATH"] || "../../logstash"
+use_logstash_source = ENV["LOGSTASH_SOURCE"] && ENV["LOGSTASH_SOURCE"].to_s == "1"
+
+if Dir.exist?(logstash_path) && use_logstash_source
+  gem 'logstash-core', :path => "#{logstash_path}/logstash-core"
+  gem 'logstash-core-plugin-api', :path => "#{logstash_path}/logstash-core-plugin-api"
+end

data/docs/index.asciidoc

@@ -0,0 +1,211 @@
+:plugin: translate
+:type: filter
+
+///////////////////////////////////////////
+START - GENERATED VARIABLES, DO NOT EDIT!
+///////////////////////////////////////////
+:version: %VERSION%
+:release_date: %RELEASE_DATE%
+:changelog_url: %CHANGELOG_URL%
+:include_path: ../../../../logstash/docs/include
+///////////////////////////////////////////
+END - GENERATED VARIABLES, DO NOT EDIT!
+///////////////////////////////////////////
+
+[id="plugins-{type}-{plugin}"]
+
+=== Translate filter plugin
+
+include::{include_path}/plugin_header.asciidoc[]
+
+==== Description
+
+A general search and replace tool that uses a configured hash
+and/or a file to determine replacement values. Currently supported are 
+YAML, JSON, and CSV files.
+
+The dictionary entries can be specified in one of two ways: First,
+the `dictionary` configuration item may contain a hash representing
+the mapping. Second, an external file (readable by logstash) may be specified
+in the `dictionary_path` configuration item. These two methods may not be used
+in conjunction; it will produce an error.
+
+Operationally, if the event field specified in the `field` configuration
+matches the EXACT contents of a dictionary entry key (or matches a regex if
+`regex` configuration item has been enabled), the field's value will be substituted
+with the matched key's value from the dictionary.
+
+By default, the translate filter will replace the contents of the 
+maching event field (in-place). However, by using the `destination`
+configuration item, you may also specify a target event field to
+populate with the new translated value.
+
+Alternatively, for simple string search and replacements for just a few values
+you might consider using the gsub function of the mutate filter.
+
+[id="plugins-{type}s-{plugin}-options"]
+==== Translate Filter Configuration Options
+
+This plugin supports the following configuration options plus the <<plugins-{type}s-{plugin}-common-options>> described later.
+
+[cols="<,<,<",options="header",]
+|=======================================================================
+|Setting |Input type|Required
+| <<plugins-{type}s-{plugin}-destination>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-dictionary>> |<<hash,hash>>|No
+| <<plugins-{type}s-{plugin}-dictionary_path>> |a valid filesystem path|No
+| <<plugins-{type}s-{plugin}-exact>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-fallback>> |<<string,string>>|No
+| <<plugins-{type}s-{plugin}-field>> |<<string,string>>|Yes
+| <<plugins-{type}s-{plugin}-override>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-refresh_interval>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-regex>> |<<boolean,boolean>>|No
+|=======================================================================
+
+Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
+filter plugins.
+
+&nbsp;
+
+[id="plugins-{type}s-{plugin}-destination"]
+===== `destination` 
+
+  * Value type is <<string,string>>
+  * Default value is `"translation"`
+
+The destination field you wish to populate with the translated code. The default
+is a field named `translation`. Set this to the same value as source if you want
+to do a substitution, in this case filter will allways succeed. This will clobber
+the old value of the source field! 
+
+[id="plugins-{type}s-{plugin}-dictionary"]
+===== `dictionary` 
+
+  * Value type is <<hash,hash>>
+  * Default value is `{}`
+
+The dictionary to use for translation, when specified in the logstash filter
+configuration item (i.e. do not use the `@dictionary_path` file).
+
+Example:
+[source,ruby]
+    filter {
+      translate {
+        dictionary => [ "100", "Continue",
+                        "101", "Switching Protocols",
+                        "merci", "thank you",
+                        "old version", "new version" ]
+      }
+    }
+
+NOTE: It is an error to specify both `dictionary` and `dictionary_path`.
+
+[id="plugins-{type}s-{plugin}-dictionary_path"]
+===== `dictionary_path` 
+
+  * Value type is <<path,path>>
+  * There is no default value for this setting.
+
+The full path of the external dictionary file. The format of the table
+should be a standard YAML, JSON, or CSV. Make sure you specify any integer-based keys
+in quotes. For example, the YAML file should look something like this:
+[source,ruby]
+    "100": Continue
+    "101": Switching Protocols
+    merci: gracias
+    old version: new version
+
+NOTE: it is an error to specify both `dictionary` and `dictionary_path`.
+
+The currently supported formats are YAML, JSON, and CSV. Format selection is
+based on the file extension: `json` for JSON, `yaml` or `yml` for YAML, and
+`csv` for CSV. The JSON format only supports simple key/value, unnested
+objects. The CSV format expects exactly two columns, with the first serving
+as the original text, and the second column as the replacement.
+
+[id="plugins-{type}s-{plugin}-exact"]
+===== `exact` 
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `true`
+
+When `exact => true`, the translate filter will populate the destination field
+with the exact contents of the dictionary value. When `exact => false`, the
+filter will populate the destination field with the result of any existing
+destination field's data, with the translated value substituted in-place.
+
+For example, consider this simple translation.yml, configured to check the `data` field:
+[source,ruby]
+    foo: bar
+
+If logstash receives an event with the `data` field set to `foo`, and `exact => true`,
+the destination field will be populated with the string `bar`.
+If `exact => false`, and logstash receives the same event, the destination field
+will be also set to `bar`. However, if logstash receives an event with the `data` field
+set to `foofing`, the destination field will be set to `barfing`.
+
+Set both `exact => true` AND `regex => `true` if you would like to match using dictionary
+keys as regular expressions. A large dictionary could be expensive to match in this case. 
+
+[id="plugins-{type}s-{plugin}-fallback"]
+===== `fallback` 
+
+  * Value type is <<string,string>>
+  * There is no default value for this setting.
+
+In case no translation occurs in the event (no matches), this will add a default
+translation string, which will always populate `field`, if the match failed.
+
+For example, if we have configured `fallback => "no match"`, using this dictionary:
+[source,ruby]
+    foo: bar
+
+Then, if logstash received an event with the field `foo` set to `bar`, the destination
+field would be set to `bar`. However, if logstash received an event with `foo` set to `nope`,
+then the destination field would still be populated, but with the value of `no match`.
+This configuration can be dynamic and include parts of the event using the `%{field}` syntax.
+
+[id="plugins-{type}s-{plugin}-field"]
+===== `field` 
+
+  * This is a required setting.
+  * Value type is <<string,string>>
+  * There is no default value for this setting.
+
+The name of the logstash event field containing the value to be compared for a
+match by the translate filter (e.g. `message`, `host`, `response_code`). 
+
+If this field is an array, only the first value will be used.
+
+[id="plugins-{type}s-{plugin}-override"]
+===== `override` 
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+If the destination (or target) field already exists, this configuration item specifies
+whether the filter should skip translation (default) or overwrite the target field
+value with the new translation value.
+
+[id="plugins-{type}s-{plugin}-refresh_interval"]
+===== `refresh_interval` 
+
+  * Value type is <<number,number>>
+  * Default value is `300`
+
+When using a dictionary file, this setting will indicate how frequently
+(in seconds) logstash will check the dictionary file for updates.
+
+[id="plugins-{type}s-{plugin}-regex"]
+===== `regex` 
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+If you'd like to treat dictionary keys as regular expressions, set `exact => true`.
+Note: this is activated only when `exact => true`.
+
+
+
+[id="plugins-{type}s-{plugin}-common-options"]
+include::{include_path}/{type}.asciidoc[]

data/logstash-filter-translate.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
 
   s.name            = 'logstash-filter-translate'
-  s.version         = '3.0.1'
+  s.version         = '3.0.2'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "A general search and replace tool which uses a configured hash and/or a YAML file to determine replacement values."
   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"
@@ -11,7 +11,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   # Files
-  s.files = Dir['lib/**/*','spec/**/*','vendor/**/*','*.gemspec','*.md','CONTRIBUTORS','Gemfile','LICENSE','NOTICE.TXT']
+  s.files = Dir["lib/**/*","spec/**/*","*.gemspec","*.md","CONTRIBUTORS","Gemfile","LICENSE","NOTICE.TXT", "vendor/jar-dependencies/**/*.jar", "vendor/jar-dependencies/**/*.rb", "VERSION", "docs/**/*"]
 
   # Tests
   s.test_files = s.files.grep(%r{^(test|spec|features)/})

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logstash-filter-translate
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 3.0.2
 platform: ruby
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2016-12-26 00:00:00.000000000 Z
+date: 2017-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
@@ -56,6 +56,7 @@ files:
 - LICENSE
 - NOTICE.TXT
 - README.md
+- docs/index.asciidoc
 - lib/logstash/filters/translate.rb
 - logstash-filter-translate.gemspec
 - spec/filters/translate_spec.rb