logstash-filter-elapsed 4.0.1 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c3ec61ddf64c40a19465060b9a7389068d5d1d6
-  data.tar.gz: f896939034bbd305e83442c4cf9533590f4948d9
+  metadata.gz: 43e924f29e3b509fea49ef12c4531b121261f39a
+  data.tar.gz: 4264b3f6734b7348557956407327fc6d6dd2cb50
 SHA512:
-  metadata.gz: 9a638fb75185ba904f0a1efeeb5a92e61093cef8d7f8a8ca30a4106fa49d5fd415df9440c83f74fee9b4756e644cb5a5c242338d7bcc641f6bab264ac2cc138d
-  data.tar.gz: df4f010ee93302d7f4b58a4056b4683012c7b1a0f314c17762eeac69f292d28441433ed0435bb6122296fd004eae643ac66e1186308cffccda0a0e8fcc5e0690
+  metadata.gz: 1c53920e39bb270d975dc066b2f58f273f909f83aa6b18ff2000215593750644fcfa16bc226b1c7ecc704d46e9ba6d6a0b58bdac39689dfc8332a64966fa0197
+  data.tar.gz: 5199b7a5f0d6b619219823b3978fd8e534b558e8236c53096d22cec9d9a79d8c04709f139cdae6a2d443eb14de1413926476defdac7614a9690fb3c48b3ba5c7

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,168 @@
+:plugin: elapsed
+: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}"]
+
+=== Elapsed filter plugin
+
+include::{include_path}/plugin_header.asciidoc[]
+
+==== Description
+
+The elapsed filter tracks a pair of start/end events and uses their
+timestamps to calculate the elapsed time between them.
+
+The filter has been developed to track the execution time of processes and
+other long tasks.
+
+The configuration looks like this:
+[source,ruby]
+    filter {
+      elapsed {
+        start_tag => "start event tag"
+        end_tag => "end event tag"
+        unique_id_field => "id field name"
+        timeout => seconds
+        new_event_on_match => true/false
+      }
+    }
+
+The events managed by this filter must have some particular properties.
+The event describing the start of the task (the "start event") must contain
+a tag equal to `start_tag`. On the other side, the event describing the end
+of the task (the "end event") must contain a tag equal to `end_tag`. Both
+these two kinds of event need to own an ID field which identify uniquely that
+particular task. The name of this field is stored in `unique_id_field`.
+
+You can use a Grok filter to prepare the events for the elapsed filter.
+An example of configuration can be:
+[source,ruby]
+    filter {
+      grok {
+        match => { "message" => "%{TIMESTAMP_ISO8601} START id: (?<task_id>.*)" }
+        add_tag => [ "taskStarted" ]
+      }
+
+      grok {
+        match => { "message" => "%{TIMESTAMP_ISO8601} END id: (?<task_id>.*)" }
+        add_tag => [ "taskTerminated" ]
+      }
+
+      elapsed {
+        start_tag => "taskStarted"
+        end_tag => "taskTerminated"
+        unique_id_field => "task_id"
+      }
+    }
+
+The elapsed filter collects all the "start events". If two, or more, "start
+events" have the same ID, only the first one is recorded, the others are
+discarded.
+
+When an "end event" matching a previously collected "start event" is
+received, there is a match. The configuration property `new_event_on_match`
+tells where to insert the elapsed information: they can be added to the
+"end event" or a new "match event" can be created. Both events store the
+following information:
+
+* the tags `elapsed` and `elapsed_match`
+* the field `elapsed_time` with the difference, in seconds, between
+  the two events timestamps
+* an ID filed with the task ID
+* the field `elapsed_timestamp_start` with the timestamp of the start event
+
+If the "end event" does not arrive before "timeout" seconds, the
+"start event" is discarded and an "expired event" is generated. This event
+contains:
+
+* the tags `elapsed` and `elapsed_expired_error`
+* a field called `elapsed_time` with the age, in seconds, of the
+  "start event"
+* an ID filed with the task ID
+* the field `elapsed_timestamp_start` with the timestamp of the "start event"
+
+
+[id="plugins-{type}s-{plugin}-options"]
+==== Elapsed 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}-end_tag>> |<<string,string>>|Yes
+| <<plugins-{type}s-{plugin}-new_event_on_match>> |<<boolean,boolean>>|No
+| <<plugins-{type}s-{plugin}-start_tag>> |<<string,string>>|Yes
+| <<plugins-{type}s-{plugin}-timeout>> |<<number,number>>|No
+| <<plugins-{type}s-{plugin}-unique_id_field>> |<<string,string>>|Yes
+|=======================================================================
+
+Also see <<plugins-{type}s-{plugin}-common-options>> for a list of options supported by all
+filter plugins.
+
+&nbsp;
+
+[id="plugins-{type}s-{plugin}-end_tag"]
+===== `end_tag` 
+
+  * This is a required setting.
+  * Value type is <<string,string>>
+  * There is no default value for this setting.
+
+The name of the tag identifying the "end event"
+
+[id="plugins-{type}s-{plugin}-new_event_on_match"]
+===== `new_event_on_match` 
+
+  * Value type is <<boolean,boolean>>
+  * Default value is `false`
+
+This property manage what to do when an "end event" matches a "start event".
+If it's set to `false` (default value), the elapsed information are added
+to the "end event"; if it's set to `true` a new "match event" is created.
+
+[id="plugins-{type}s-{plugin}-start_tag"]
+===== `start_tag` 
+
+  * This is a required setting.
+  * Value type is <<string,string>>
+  * There is no default value for this setting.
+
+The name of the tag identifying the "start event"
+
+[id="plugins-{type}s-{plugin}-timeout"]
+===== `timeout` 
+
+  * Value type is <<number,number>>
+  * Default value is `1800`
+
+The amount of seconds after an "end event" can be considered lost.
+The corresponding "start event" is discarded and an "expired event"
+is generated. The default value is 30 minutes (1800 seconds).
+
+[id="plugins-{type}s-{plugin}-unique_id_field"]
+===== `unique_id_field` 
+
+  * This is a required setting.
+  * Value type is <<string,string>>
+  * There is no default value for this setting.
+
+The name of the field containing the task ID.
+This value must uniquely identify the task in the system, otherwise
+it's impossible to match the couple of events.
+
+
+
+[id="plugins-{type}s-{plugin}-common-options"]
+include::{include_path}/{type}.asciidoc[]

data/logstash-filter-elapsed.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
 
   s.name            = 'logstash-filter-elapsed'
-  s.version         = '4.0.1'
+  s.version         = '4.0.2'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "This filter tracks a pair of start/end events and calculates the elapsed time between them."
   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-elapsed
 version: !ruby/object:Gem::Version
-  version: 4.0.1
+  version: 4.0.2
 platform: ruby
 authors:
 - Elastic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-02-15 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/elapsed.rb
 - logstash-filter-elapsed.gemspec
 - spec/filters/elapsed_spec.rb