Deprecates failure_type_logging_whitelist option in favor of `silen…

…ce_errors_in_log` (elastic#1068)

Introduce a new setting named silence_errors_in_log with exact same behavior of failure_type_logging_whitelist. It print a deprecation log message if failure_type_logging_whitelist is used.

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 11.7.0
+ - Feature: deprecates the `failure_type_logging_whitelist` configuration option, renaming it `silence_errors_in_log` [#1068](https://github.com/logstash-plugins/logstash-output-elasticsearch/pull/1068)
+
 ## 11.6.0
  - Added support for `ca_trusted_fingerprint` when run on Logstash 8.3+ [#1074](https://github.com/logstash-plugins/logstash-output-elasticsearch/pull/1074)
 

docs/index.asciidoc

@@ -332,6 +332,7 @@ This plugin supports the following configuration options plus the
 | <<plugins-{type}s-{plugin}-index>> |<<string,string>>|No
 | <<plugins-{type}s-{plugin}-keystore>> |a valid filesystem path|No
 | <<plugins-{type}s-{plugin}-keystore_password>> |<<password,password>>|No
+| <<plugins-{type}s-{plugin}-silence_errors_in_log>> |<<array,array>>|No
 | <<plugins-{type}s-{plugin}-manage_template>> |<<boolean,boolean>>|No
 | <<plugins-{type}s-{plugin}-parameters>> |<<hash,hash>>|No
 | <<plugins-{type}s-{plugin}-parent>> |<<string,string>>|No
@@ -584,9 +585,7 @@ of this setting affects the _default_ values of:
   * Value type is <<array,array>>
   * Default value is `[]`
 
-Set the Elasticsearch errors in the whitelist that you don't want to log.
-A useful example is when you want to skip all 409 errors
-which are `document_already_exists_exception`.
+NOTE: Deprecated, refer to <<plugins-{type}s-{plugin}-silence_errors_in_log>>.
 
 [id="plugins-{type}s-{plugin}-custom_headers"]
 ===== `custom_headers`
@@ -962,6 +961,25 @@ Set variable name passed to script (scripted update)
 
 if enabled, script is in charge of creating non-existent document (scripted update)
 
+[id="plugins-{type}s-{plugin}-silence_errors_in_log"]
+===== `silence_errors_in_log`
+
+* Value type is <<array,array>>
+* Default value is `[]`
+
+Defines the list of Elasticsearch errors that you don't want to log.
+A useful example is when you want to skip all 409 errors
+which are `document_already_exists_exception`.
+
+[source,ruby]
+    output {
+      elasticsearch {
+        silence_errors_in_log => ["document_already_exists_exception"]
+      }
+    }
+
+NOTE: Deprecates <<plugins-{type}s-{plugin}-failure_type_logging_whitelist>>.
+
 [id="plugins-{type}s-{plugin}-sniffing"]
 ===== `sniffing`
 

lib/logstash/outputs/elasticsearch.rb

@@ -266,6 +266,14 @@ def initialize(*params)
   end
 
   def register
+    if !failure_type_logging_whitelist.empty?
+      log_message = "'failure_type_logging_whitelist' is deprecated and in a future version of Elasticsearch " +
+        "output plugin will be removed, please use 'silence_errors_in_log' instead."
+      @deprecation_logger.deprecated log_message
+      @logger.warn log_message
+      @silence_errors_in_log = silence_errors_in_log | failure_type_logging_whitelist
+    end
+
     @after_successful_connection_done = Concurrent::AtomicBoolean.new(false)
     @stopping = Concurrent::AtomicBoolean.new(false)
 

lib/logstash/plugin_mixins/elasticsearch/api_configs.rb

@@ -99,10 +99,14 @@ module APIConfigs
         # a timeout occurs, the request will be retried.
         :timeout => { :validate => :number, :default => 60 },
 
-        # Set the Elasticsearch errors in the whitelist that you don't want to log.
+        # Deprecated, refer to `silence_errors_in_log`.
+        :failure_type_logging_whitelist => { :validate => :array, :default => [] },
+
+        # Defines the list of Elasticsearch errors that you don't want to log.
         # A useful example is when you want to skip all 409 errors
         # which are `document_already_exists_exception`.
-        :failure_type_logging_whitelist => { :validate => :array, :default => [] },
+        # Deprecates `failure_type_logging_whitelist`.
+        :silence_errors_in_log => { :validate => :array, :default => [] },
 
         # While the output tries to reuse connections efficiently we have a maximum.
         # This sets the maximum number of open connections the output will create.

lib/logstash/plugin_mixins/elasticsearch/common.rb

@@ -284,7 +284,7 @@ def submit(actions)
     end
 
     def log_failure_type?(failure)
-      !failure_type_logging_whitelist.include?(failure["type"])
+      !silence_errors_in_log.include?(failure["type"])
     end
 
     # Rescue retryable errors during bulk submission

logstash-output-elasticsearch.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name            = 'logstash-output-elasticsearch'
-  s.version         = '11.6.0'
+  s.version         = '11.7.0'
   s.licenses        = ['apache-2.0']
   s.summary         = "Stores logs in Elasticsearch"
   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"

spec/unit/outputs/error_whitelist_spec.rb

@@ -45,8 +45,8 @@
     end
   end
 
-  describe "when failure logging is disabled for docuemnt exists error" do
-    let(:settings) { super().merge("failure_type_logging_whitelist" => ["document_already_exists_exception"]) }
+  describe "when failure logging is disabled for document exists error" do
+    let(:settings) { super().merge("silence_errors_in_log" => ["document_already_exists_exception"]) }
 
     it "should log a failure on the action" do
       expect(subject.logger).not_to have_received(:warn).with("Failed action", anything)