Add a target field support. (#196)

* Introduces a target field as a field reference (mixin validated) where if set result is placed into the target.

* Simplifies the set extracted values to the event with target logic. Applies setting to target with aggregations similarly with es-input.

* Mention to target in each fields which can be placed in the target. Docs info fields are placed in target field.

---------

Co-authored-by: Rye Biesemeyer <yaauie@users.noreply.github.com>

Author: mashhurs

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 4.2.0
+  - Add `target` configuration option to store the result into it [#196](https://github.com/logstash-plugins/logstash-filter-elasticsearch/pull/196)
+
 ## 4.1.1
   - Add elastic-transport client support used in elasticsearch-ruby 8.x [#191](https://github.com/logstash-plugins/logstash-filter-elasticsearch/pull/191)
 

docs/index.asciidoc

@@ -162,6 +162,7 @@ NOTE: As of version `4.0.0` of this plugin, a number of previously deprecated se
 | <<plugins-{type}s-{plugin}-ssl_truststore_type>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-ssl_verification_mode>> |<<string,string>>, one of `["full", "none"]`|No
 | <<plugins-{type}s-{plugin}-tag_on_failure>> |<<array,array>>|No
+| <<plugins-{type}s-{plugin}-target>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-user>> |<<string,string>>|No
 |=======================================================================
 
@@ -175,8 +176,11 @@ filter plugins.
 
   * Value type is <<hash,hash>>
   * Default value is `{}`
+  * Format: `"aggregation_name" => "[path][on][event]"`:
+  ** `aggregation_name`: aggregation name in result from {es}
+  ** `[path][on][event]`: path for where to place the value on the current event, using field-reference notation
 
-Hash of aggregation names to copy from elasticsearch response into Logstash event fields
+A mapping of aggregations to copy into the <<plugins-{type}s-{plugin}-target>> of the current event.
 
 Example:
 [source,ruby]
@@ -246,8 +250,11 @@ These custom headers will override any headers previously set by the plugin such
 
   * Value type is <<hash,hash>>
   * Default value is `{}`
+  * Format: `"path.in.source" => "[path][on][event]"`:
+  ** `path.in.source`: field path in document source of result from {es}, using dot-notation
+  ** `[path][on][event]`: path for where to place the value on the current event, using field-reference notation
 
-Hash of docinfo fields to copy from old event (found via elasticsearch) into new event
+A mapping of docinfo (`_source`) fields to copy into the <<plugins-{type}s-{plugin}-target>> of the current event.
 
 Example:
 [source,ruby]
@@ -273,9 +280,11 @@ Whether results should be sorted or not
 
   * Value type is <<array,array>>
   * Default value is `{}`
+  * Format: `"path.in.result" => "[path][on][event]"`:
+  ** `path.in.result`: field path in indexed result from {es}, using dot-notation
+  ** `[path][on][event]`: path for where to place the value on the current event, using field-reference notation
 
-An array of fields to copy from the old event (found via elasticsearch) into the
-new event, currently being processed.
+A mapping of indexed fields to copy into the <<plugins-{type}s-{plugin}-target>> of the current event.
 
 In the following example, the values of `@timestamp` and `event_id` on the event
 found via elasticsearch are copied to the current event's
@@ -523,6 +532,43 @@ WARNING: Setting certificate verification to `none` disables many security benef
 
 Tags the event on failure to look up previous log event information. This can be used in later analysis.
 
+[id="plugins-{type}s-{plugin}-target"]
+===== `target`
+
+* Value type is <<string,string>>
+* There is no default value for this setting.
+
+Define the target field for placing the result data.
+If this setting is omitted, the target will be the root (top level) of the event.
+
+The destination fields specified in <<plugins-{type}s-{plugin}-fields>>, <<plugins-{type}s-{plugin}-aggregation_fields>>, and <<plugins-{type}s-{plugin}-docinfo_fields>> are relative to this target.
+
+For example, if you want the data to be put in the `operation` field:
+[source,ruby]
+if [type] == "end" {
+    filter {
+      query => "type:start AND transaction:%{[transactionId]}"
+      elasticsearch {
+        target => "transaction"
+        fields => {
+          "@timestamp" => "started"
+          "transaction_id" => "id"
+        }
+      }
+    }
+}
+
+`fields` fields will be expanded into a data structure in the `target` field, overall shape looks like this:
+[source,ruby]
+    {
+      "transaction" => {
+        "started" => "2025-04-29T12:01:46.263Z"
+        "id" => "1234567890"
+      }
+    }
+
+NOTE: when writing to a field that already exists on the event, the previous value will be overwritten.
+
 [id="plugins-{type}s-{plugin}-user"]
 ===== `user` 
 

lib/logstash/filters/elasticsearch.rb

@@ -2,12 +2,19 @@
 require "logstash/filters/base"
 require "logstash/namespace"
 require "logstash/json"
+require 'logstash/plugin_mixins/ecs_compatibility_support'
+require 'logstash/plugin_mixins/ecs_compatibility_support/target_check'
 require 'logstash/plugin_mixins/ca_trusted_fingerprint_support'
+require 'logstash/plugin_mixins/validator_support/field_reference_validation_adapter'
 require "monitor"
 
 require_relative "elasticsearch/client"
 
 class LogStash::Filters::Elasticsearch < LogStash::Filters::Base
+
+  include LogStash::PluginMixins::ECSCompatibilitySupport
+  include LogStash::PluginMixins::ECSCompatibilitySupport::TargetCheck
+
   config_name "elasticsearch"
 
   # List of elasticsearch hosts to use for querying.
@@ -118,6 +125,9 @@ class LogStash::Filters::Elasticsearch < LogStash::Filters::Base
   # Tags the event on failure to look up geo information. This can be used in later analysis.
   config :tag_on_failure, :validate => :array, :default => ["_elasticsearch_lookup_failure"]
 
+  # If set, the the result set will be nested under the target field
+  config :target, :validate => :field_reference
+
   # How many times to retry on failure?
   config :retry_on_failure, :validate => :number, :default => 0
 
@@ -205,25 +215,27 @@ def filter(event)
         matched = true
         @fields.each do |old_key, new_key|
           old_key_path = extract_path(old_key)
-          set = resultsHits.map do |doc|
+          extracted_hit_values = resultsHits.map do |doc|
             extract_value(doc["_source"], old_key_path)
           end
-          event.set(new_key, set.count > 1 ? set : set.first)
+          value_to_set = extracted_hit_values.count > 1 ? extracted_hit_values : extracted_hit_values.first
+          set_to_event_target(event, new_key, value_to_set)
         end
         @docinfo_fields.each do |old_key, new_key|
           old_key_path = extract_path(old_key)
-          set = resultsHits.map do |doc|
+          extracted_docs_info = resultsHits.map do |doc|
             extract_value(doc, old_key_path)
           end
-          event.set(new_key, set.count > 1 ? set : set.first)
+          value_to_set = extracted_docs_info.count > 1 ? extracted_docs_info : extracted_docs_info.first
+          set_to_event_target(event, new_key, value_to_set)
         end
       end
 
       resultsAggs = results["aggregations"]
       if !resultsAggs.nil? && !resultsAggs.empty?
         matched = true
         @aggregation_fields.each do |agg_name, ls_field|
-          event.set(ls_field, resultsAggs[agg_name])
+          set_to_event_target(event, ls_field, resultsAggs[agg_name])
         end
       end
 
@@ -256,6 +268,18 @@ def prepare_user_agent
 
   private
 
+  # if @target is defined, creates a nested structure to inject result into target field
+  # if not defined, directly sets to the top-level event field
+  # @param event [LogStash::Event]
+  # @param new_key [String] name of the field to set
+  # @param value_to_set [Array] values to set
+  # @return [void]
+  def set_to_event_target(event, new_key, value_to_set)
+    key_to_set = target ? "[#{target}][#{new_key}]" : new_key
+
+    event.set(key_to_set, value_to_set)
+  end
+
   def client_options
     @client_options ||= {
       :user => @user,

logstash-filter-elasticsearch.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
 
   s.name            = 'logstash-filter-elasticsearch'
-  s.version         = '4.1.1'
+  s.version         = '4.2.0'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "Copies fields from previous log events in Elasticsearch to current events "
   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"
@@ -23,7 +23,9 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency "logstash-core-plugin-api", ">= 1.60", "<= 2.99"
   s.add_runtime_dependency 'elasticsearch', ">= 7.14.9", '< 9'
   s.add_runtime_dependency 'manticore', ">= 0.7.1"
+  s.add_runtime_dependency 'logstash-mixin-ecs_compatibility_support', '~> 1.3'
   s.add_runtime_dependency 'logstash-mixin-ca_trusted_fingerprint_support', '~> 1.0'
+  s.add_runtime_dependency 'logstash-mixin-validator_support', '~> 1.0'
   s.add_development_dependency 'cabin', ['~> 0.6']
   s.add_development_dependency 'webrick'
   s.add_development_dependency 'logstash-devutils'

spec/filters/elasticsearch_spec.rb

@@ -864,6 +864,33 @@ def wait_receive_request
     end
   end
 
+  describe "#set_to_event_target" do
+
+    context "when `@target` is nil, default behavior" do
+      let(:config) {{ }}
+
+      it "sets the value directly to the top-level event field" do
+        plugin.send(:set_to_event_target, event, "new_field", %w[value1 value2])
+        expect(event.get("new_field")).to eq(%w[value1 value2])
+      end
+    end
+
+    context "when @target is defined" do
+      let(:config) {{ "target" => "nested" }}
+
+      it "creates a nested structure under the target field" do
+        plugin.send(:set_to_event_target, event, "new_field", %w[value1 value2])
+        expect(event.get("nested")).to eq({ "new_field" => %w[value1 value2] })
+      end
+
+      it "overwrites existing target field with new data" do
+        event.set("nested", { "existing_field" => "existing_value", "new_field" => "value0" })
+        plugin.send(:set_to_event_target, event, "new_field", ["value1"])
+        expect(event.get("nested")).to eq({ "existing_field" => "existing_value", "new_field" => ["value1"] })
+      end
+    end
+  end
+
   def extract_transport(client)
     # on 7x: client.transport.transport
     # on >=8.x: client.transport

spec/filters/integration/elasticsearch_spec.rb

@@ -84,7 +84,9 @@
     end
 
     it "fails to register plugin" do
-      expect { plugin.register }.to raise_error Elasticsearch::Transport::Transport::Errors::Unauthorized
+      expect { plugin.register }.to raise_error elastic_ruby_v8_client_available? ?
+                                                  Elastic::Transport::Transport::Errors::Unauthorized :
+                                                  Elasticsearch::Transport::Transport::Errors::Unauthorized
     end
 
   end if ELASTIC_SECURITY_ENABLED
@@ -150,5 +152,10 @@
       end
     end
   end
-
+  def elastic_ruby_v8_client_available?
+    Elasticsearch::Transport
+    false
+  rescue NameError # NameError: uninitialized constant Elasticsearch::Transport if Elastic Ruby client is not available
+    true
+  end
 end