Log deprecations to dedicated log file

This ensures that deprecation warnings coming
from both Ruby and Rails are logged to a new
log file, deprecations_json.log.

Changelog: added

Gemfile

@@ -335,6 +335,8 @@ gem 'method_source', '~> 1.0', require: false
 gem 'webrick', '~> 1.6.1', require: false
 gem 'prometheus-client-mmap', '~> 0.12.0', require: 'prometheus/client'
 
+gem 'warning', '~> 1.2.0'
+
 group :development do
   gem 'lefthook', '~> 0.7.0', require: false
   gem 'solargraph', '~> 0.42', require: false

Gemfile.lock

@@ -1339,6 +1339,7 @@ GEM
     vmstat (2.3.0)
     warden (1.2.8)
       rack (>= 2.0.6)
+    warning (1.2.0)
     webauthn (2.3.0)
       android_key_attestation (~> 0.3.0)
       awrence (~> 1.1)
@@ -1648,6 +1649,7 @@ DEPENDENCIES
   validates_hostname (~> 1.0.11)
   version_sorter (~> 2.2.4)
   vmstat (~> 2.3.0)
+  warning (~> 1.2.0)
   webauthn (~> 2.3)
   webmock (~> 3.9.1)
   webrick (~> 1.6.1)

config/initializers/0_log_deprecations.rb

+# frozen_string_literal: true
+
+def log_deprecations?
+  via_env_var = Gitlab::Utils.to_boolean(ENV['GITLAB_LOG_DEPRECATIONS'])
+  # enable by default during development unless explicitly turned off
+  via_env_var.nil? ? Rails.env.development? : via_env_var
+end
+
+if log_deprecations?
+  # Log deprecation warnings emitted through Kernel#warn, such as from gems or
+  # the Ruby VM.
+  Warning.process(/.+is deprecated$/) do |warning|
+    Gitlab::DeprecationJsonLogger.info(message: warning.strip, source: 'ruby')
+    # Returning :default means we continue emitting this to stderr as well.
+    :default
+  end
+
+  # Log deprecation warnings emitted from Rails (see ActiveSupport::Deprecation).
+  ActiveSupport::Notifications.subscribe('deprecation.rails') do |name, start, finish, id, payload|
+    Gitlab::DeprecationJsonLogger.info(message: payload[:message].strip, source: 'rails')
+  end
+end

lib/gitlab/deprecation_json_logger.rb

+# frozen_string_literal: true
+
+module Gitlab
+  class DeprecationJsonLogger < Gitlab::JsonLogger
+    def self.file_name_noext
+      'deprecation_json'
+    end
+  end
+end

spec/initializers/0_log_deprecations_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe '0_log_deprecations' do
+  def load_initializer
+    load Rails.root.join('config/initializers/0_log_deprecations.rb')
+  end
+
+  let(:env_var) { '1' }
+
+  before do
+    stub_env('GITLAB_LOG_DEPRECATIONS', env_var)
+    load_initializer
+  end
+
+  after do
+    # reset state changed by initializer
+    Warning.clear
+    ActiveSupport::Notifications.unsubscribe('deprecation.rails')
+  end
+
+  context 'for Ruby deprecations' do
+    context 'when catching deprecations through Kernel#warn' do
+      it 'also logs them to deprecation logger' do
+        expect(Gitlab::DeprecationJsonLogger).to receive(:info).with(
+          message: 'ABC gem is deprecated',
+          source: 'ruby'
+        )
+
+        expect { warn('ABC gem is deprecated') }.to output.to_stderr
+      end
+    end
+
+    context 'for other messages from Kernel#warn' do
+      it 'does not log them to deprecation logger' do
+        expect(Gitlab::DeprecationJsonLogger).not_to receive(:info)
+
+        expect { warn('Sure is hot today') }.to output.to_stderr
+      end
+    end
+
+    context 'when disabled via environment' do
+      let(:env_var) { '0' }
+
+      it 'does not log them to deprecation logger' do
+        expect(Gitlab::DeprecationJsonLogger).not_to receive(:info)
+
+        expect { warn('ABC gem is deprecated') }.to output.to_stderr
+      end
+    end
+  end
+
+  context 'for Rails deprecations' do
+    it 'logs them to deprecation logger' do
+      expect(Gitlab::DeprecationJsonLogger).to receive(:info).with(
+        message: match(/^DEPRECATION WARNING: ABC will be removed/),
+        source: 'rails'
+      )
+
+      expect { ActiveSupport::Deprecation.warn('ABC will be removed') }.to output.to_stderr
+    end
+
+    context 'when disabled via environment' do
+      let(:env_var) { '0' }
+
+      it 'does not log them to deprecation logger' do
+        expect(Gitlab::DeprecationJsonLogger).not_to receive(:info)
+
+        expect { ActiveSupport::Deprecation.warn('ABC will be removed') }.to output.to_stderr
+      end
+    end
+  end
+end