diff --git a/logstash-core/lib/logstash/environment.rb b/logstash-core/lib/logstash/environment.rb index 3c2bd737785..80f49a88e15 100644 --- a/logstash-core/lib/logstash/environment.rb +++ b/logstash-core/lib/logstash/environment.rb @@ -73,10 +73,10 @@ module Environment Setting::Boolean.new("enable-local-plugin-development", false), Setting::String.new("log.format", "plain", true, ["json", "plain"]), Setting::Boolean.new("log.format.json.fix_duplicate_message_fields", false), - Setting::Boolean.new("api.enabled", true).with_deprecated_alias("http.enabled"), - Setting::String.new("api.http.host", "127.0.0.1").with_deprecated_alias("http.host"), - Setting::PortRange.new("api.http.port", 9600..9700).with_deprecated_alias("http.port"), - Setting::String.new("api.environment", "production").with_deprecated_alias("http.environment"), + Setting::Boolean.new("api.enabled", true).with_deprecated_alias("http.enabled", "9"), + Setting::String.new("api.http.host", "127.0.0.1").with_deprecated_alias("http.host", "9"), + Setting::PortRange.new("api.http.port", 9600..9700).with_deprecated_alias("http.port", "9"), + Setting::String.new("api.environment", "production").with_deprecated_alias("http.environment", "9"), Setting::String.new("api.auth.type", "none", true, %w(none basic)), Setting::String.new("api.auth.basic.username", nil, false).nullable, Setting::Password.new("api.auth.basic.password", nil, false).nullable, diff --git a/logstash-core/lib/logstash/runner.rb b/logstash-core/lib/logstash/runner.rb index 6507d7fa3a7..69c5c9e73fd 100644 --- a/logstash-core/lib/logstash/runner.rb +++ b/logstash-core/lib/logstash/runner.rb @@ -253,15 +253,18 @@ class LogStash::Runner < Clamp::StrictCommand deprecated_option ["--http.enabled"], :flag, I18n.t("logstash.runner.flag.http_enabled"), - :new_flag => "api.enabled", :passthrough => true # use settings to disambiguate + :new_flag => "api.enabled", :passthrough => true, # use settings to disambiguate + :obsoleted_version => "9" deprecated_option ["--http.host"], "HTTP_HOST", I18n.t("logstash.runner.flag.http_host"), - :new_flag => "api.http.host", :passthrough => true # use settings to disambiguate + :new_flag => "api.http.host", :passthrough => true, # use settings to disambiguate + :obsoleted_version => "9" deprecated_option ["--http.port"], "HTTP_PORT", I18n.t("logstash.runner.flag.http_port"), - :new_flag => "api.http.port", :passthrough => true # use settings to disambiguate + :new_flag => "api.http.port", :passthrough => true, # use settings to disambiguate + :obsoleted_version => "9" deprecated_option ["--event_api.tags.illegal"], "STRING", I18n.t("logstash.runner.flag.event_api.tags.illegal"), diff --git a/logstash-core/lib/logstash/settings.rb b/logstash-core/lib/logstash/settings.rb index 5d2fbd588df..d340390646b 100644 --- a/logstash-core/lib/logstash/settings.rb +++ b/logstash-core/lib/logstash/settings.rb @@ -334,8 +334,8 @@ def validate_value validate(value) end - def with_deprecated_alias(deprecated_alias_name) - SettingWithDeprecatedAlias.wrap(self, deprecated_alias_name) + def with_deprecated_alias(deprecated_alias_name, obsoleted_version=nil) + SettingWithDeprecatedAlias.wrap(self, deprecated_alias_name, obsoleted_version) end ## @@ -847,10 +847,11 @@ def validate_value class DeprecatedAlias < SimpleDelegator # include LogStash::Util::Loggable alias_method :wrapped, :__getobj__ - attr_reader :canonical_proxy + attr_reader :canonical_proxy, :obsoleted_version - def initialize(canonical_proxy, alias_name) + def initialize(canonical_proxy, alias_name, obsoleted_version) @canonical_proxy = canonical_proxy + @obsoleted_version = obsoleted_version clone = @canonical_proxy.canonical_setting.clone clone.update_wrapper(clone.wrapped_setting.deprecate(alias_name)) @@ -882,9 +883,15 @@ def observe_post_process private def do_log_setter_deprecation - deprecation_logger.deprecated(I18n.t("logstash.settings.deprecation.set", - :deprecated_alias => name, - :canonical_name => canonical_proxy.name)) + deprecation_logger.deprecated( + I18n.t("logstash.settings.deprecation.set", + :deprecated_alias => name, + :canonical_name => canonical_proxy.name, + :obsoleted_sentences => + @obsoleted_version.nil? ? + I18n.t("logstash.settings.deprecation.obsoleted_future") : + I18n.t("logstash.settings.deprecation.obsoleted_version", :obsoleted_version => @obsoleted_version)) + ) end end @@ -901,10 +908,11 @@ class SettingWithDeprecatedAlias < SimpleDelegator # including the canonical setting and a deprecated alias. # @param canonical_setting [Setting]: the setting to wrap # @param deprecated_alias_name [String]: the name for the deprecated alias + # @param obsoleted_version [String]: the version of Logstash that deprecated alias will be removed # # @return [SettingWithDeprecatedAlias,DeprecatedSetting] - def self.wrap(canonical_setting, deprecated_alias_name) - setting_proxy = new(canonical_setting, deprecated_alias_name) + def self.wrap(canonical_setting, deprecated_alias_name, obsoleted_version=nil) + setting_proxy = new(canonical_setting, deprecated_alias_name, obsoleted_version) [setting_proxy, setting_proxy.deprecated_alias] end @@ -912,10 +920,10 @@ def self.wrap(canonical_setting, deprecated_alias_name) attr_reader :deprecated_alias alias_method :canonical_setting, :__getobj__ - def initialize(canonical_setting, deprecated_alias_name) + def initialize(canonical_setting, deprecated_alias_name, obsoleted_version) super(canonical_setting) - @deprecated_alias = DeprecatedAlias.new(self, deprecated_alias_name) + @deprecated_alias = DeprecatedAlias.new(self, deprecated_alias_name, obsoleted_version) end def set(value) diff --git a/logstash-core/locales/en.yml b/logstash-core/locales/en.yml index 645355eaea4..f338a1f0f8c 100644 --- a/logstash-core/locales/en.yml +++ b/logstash-core/locales/en.yml @@ -477,7 +477,11 @@ en: deprecation: set: >- The setting `%{deprecated_alias}` is a deprecated alias for `%{canonical_name}` - and will be removed in a future release of Logstash. Please use %{canonical_name} instead + %{obsoleted_sentences} Please use `%{canonical_name}` instead + obsoleted_future: >- + and will be removed in a future release of Logstash. + obsoleted_version: >- + and will be removed in version %{obsoleted_version}. queried: >- The value of setting `%{canonical_name}` has been queried by its deprecated alias `%{deprecated_alias}`. Code should be updated to query `%{canonical_name}` instead diff --git a/logstash-core/spec/logstash/settings/setting_with_deprecated_alias_spec.rb b/logstash-core/spec/logstash/settings/setting_with_deprecated_alias_spec.rb index 481e387ba03..1b199d135e1 100644 --- a/logstash-core/spec/logstash/settings/setting_with_deprecated_alias_spec.rb +++ b/logstash-core/spec/logstash/settings/setting_with_deprecated_alias_spec.rb @@ -105,6 +105,38 @@ expect { settings.get_setting(canonical_setting_name).deprecated_alias.validate_value }.to_not raise_error end end + + context 'obsoleted version' do + before(:each) do + settings.register(subject.with_deprecated_alias(deprecated_name, "9")) + end + + describe "ruby string setting" do + let(:new_value) { "ironman" } + let(:old_value) { "iron man" } + let(:canonical_name) { "iron.setting" } + let(:deprecated_name) { "iron.oxide.setting" } + subject { LogStash::Setting::String.new(canonical_name, old_value, true) } + + it 'logs a deprecation warning with target remove version' do + settings.set(deprecated_name, new_value) + expect(LogStash::Settings.deprecation_logger).to have_received(:deprecated) + .with(a_string_including(deprecated_name)) + .with(a_string_including("version 9")) + end + end + describe "java boolean setting" do + let(:new_value) { false } + let(:old_value) { true } + let(:canonical_name) { "bool.setting" } + let(:deprecated_name) { "boo.setting" } + subject { LogStash::Setting::Boolean.new(canonical_name, old_value, true) } + + it 'does not raise error' do + expect { settings.set(deprecated_name, new_value) }.to_not raise_error + end + end + end end context "when only the canonical setting is set" do diff --git a/logstash-core/src/main/java/org/logstash/settings/BaseSetting.java b/logstash-core/src/main/java/org/logstash/settings/BaseSetting.java index b08408393df..72be91a13e3 100644 --- a/logstash-core/src/main/java/org/logstash/settings/BaseSetting.java +++ b/logstash-core/src/main/java/org/logstash/settings/BaseSetting.java @@ -193,7 +193,10 @@ public void format(List output) { } public List> withDeprecatedAlias(String deprecatedAlias) { - return SettingWithDeprecatedAlias.wrap(this, deprecatedAlias); + return withDeprecatedAlias(deprecatedAlias, null); + } + public List> withDeprecatedAlias(String deprecatedAlias, String obsoletedVersion) { + return SettingWithDeprecatedAlias.wrap(this, deprecatedAlias, obsoletedVersion); } public Setting nullable() { diff --git a/logstash-core/src/main/java/org/logstash/settings/DeprecatedAlias.java b/logstash-core/src/main/java/org/logstash/settings/DeprecatedAlias.java index d2b8eac17e3..8d4a44d6372 100644 --- a/logstash-core/src/main/java/org/logstash/settings/DeprecatedAlias.java +++ b/logstash-core/src/main/java/org/logstash/settings/DeprecatedAlias.java @@ -33,19 +33,32 @@ public final class DeprecatedAlias extends SettingDelegator { private static final DeprecationLogger DEPRECATION_LOGGER = new DefaultDeprecationLogger(LOGGER); - private SettingWithDeprecatedAlias canonicalProxy; + private final SettingWithDeprecatedAlias canonicalProxy; - DeprecatedAlias(SettingWithDeprecatedAlias canonicalProxy, String aliasName) { + private final String obsoletedVersion; + + DeprecatedAlias(SettingWithDeprecatedAlias canonicalProxy, String aliasName, String obsoletedVersion) { super(canonicalProxy.getCanonicalSetting().deprecate(aliasName)); this.canonicalProxy = canonicalProxy; + this.obsoletedVersion = obsoletedVersion; } // Because loggers are configure after the Settings declaration, this method is intended for lazy-logging // check https://github.com/elastic/logstash/pull/16339 public void observePostProcess() { if (isSet()) { - DEPRECATION_LOGGER.deprecated("The setting `{}` is a deprecated alias for `{}` and will be removed in a " + - "future release of Logstash. Please use `{}` instead", getName(), canonicalProxy.getName(), canonicalProxy.getName()); + StringBuilder sb = new StringBuilder(); + sb.append("The setting `").append(getName()).append("` is a deprecated alias for `").append(canonicalProxy.getName()).append("`"); + + if (this.obsoletedVersion != null && !this.obsoletedVersion.isEmpty()) { + sb.append(" and will be removed in version ").append(this.obsoletedVersion).append("."); + } else { + sb.append(" and will be removed in a future release of Logstash."); + } + + sb.append(" Please use `").append(canonicalProxy.getName()).append("` instead"); + + DEPRECATION_LOGGER.deprecated(sb.toString()); } } diff --git a/logstash-core/src/main/java/org/logstash/settings/SettingWithDeprecatedAlias.java b/logstash-core/src/main/java/org/logstash/settings/SettingWithDeprecatedAlias.java index 3b3b0678ed7..a213304b7e0 100644 --- a/logstash-core/src/main/java/org/logstash/settings/SettingWithDeprecatedAlias.java +++ b/logstash-core/src/main/java/org/logstash/settings/SettingWithDeprecatedAlias.java @@ -38,21 +38,22 @@ public class SettingWithDeprecatedAlias extends SettingDelegator { * including the canonical setting and a deprecated alias. * @param canonicalSetting the setting to wrap * @param deprecatedAliasName the name for the deprecated alias + * @param obsoletedVersion the version of Logstash that deprecated alias will be removed * * @return List of [SettingWithDeprecatedAlias, DeprecatedAlias] * */ - static List> wrap(BaseSetting canonicalSetting, String deprecatedAliasName) { - final SettingWithDeprecatedAlias settingProxy = new SettingWithDeprecatedAlias<>(canonicalSetting, deprecatedAliasName); + static List> wrap(BaseSetting canonicalSetting, String deprecatedAliasName, String obsoletedVersion) { + final SettingWithDeprecatedAlias settingProxy = new SettingWithDeprecatedAlias<>(canonicalSetting, deprecatedAliasName, obsoletedVersion); return Arrays.asList(settingProxy, settingProxy.deprecatedAlias); } private DeprecatedAlias deprecatedAlias; @SuppressWarnings("this-escape") - protected SettingWithDeprecatedAlias(BaseSetting canonicalSetting, String deprecatedAliasName) { + protected SettingWithDeprecatedAlias(BaseSetting canonicalSetting, String deprecatedAliasName, String obsoletedVersion) { super(canonicalSetting); - this.deprecatedAlias = new DeprecatedAlias(this, deprecatedAliasName); + this.deprecatedAlias = new DeprecatedAlias(this, deprecatedAliasName, obsoletedVersion); } BaseSetting getCanonicalSetting() {