berkeley_library-logging 0.2.0

data/Rakefile

@@ -0,0 +1,31 @@
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('Gemfile', __dir__)
+require 'bundler/setup' # Set up gems listed in the Gemfile.
+
+# ------------------------------------------------------------
+# Application code
+
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+# ------------------------------------------------------------
+# CI
+
+if ENV['CI']
+  ENV['RAILS_ENV'] = 'test'
+  ENV['GENERATE_REPORTS'] ||= 'true'
+end
+
+# ------------------------------------------------------------
+# Custom tasks
+
+desc 'Remove artifacts directory'
+task :clean do
+  FileUtils.rm_rf('artifacts')
+end
+
+desc 'Check test coverage, check code style, check gems for vulnerabilities'
+task check: %w[coverage rubocop bundle:audit]
+
+desc 'Clean, check, build gem'
+task default: %i[clean check gem]

data/berkeley_library-logging.gemspec

@@ -0,0 +1,47 @@
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+ruby_version = begin
+  ruby_version_file = File.expand_path('.ruby-version', __dir__)
+  File.read(ruby_version_file).strip
+end
+
+require 'berkeley_library/logging/module_info'
+
+Gem::Specification.new do |spec|
+  spec.name = BerkeleyLibrary::Logging::ModuleInfo::NAME
+  spec.author = BerkeleyLibrary::Logging::ModuleInfo::AUTHOR
+  spec.email = BerkeleyLibrary::Logging::ModuleInfo::AUTHOR_EMAIL
+  spec.summary = BerkeleyLibrary::Logging::ModuleInfo::SUMMARY
+  spec.description = BerkeleyLibrary::Logging::ModuleInfo::DESCRIPTION
+  spec.license = BerkeleyLibrary::Logging::ModuleInfo::LICENSE
+  spec.version = BerkeleyLibrary::Logging::ModuleInfo::VERSION
+  spec.homepage = BerkeleyLibrary::Logging::ModuleInfo::HOMEPAGE
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = ">= #{ruby_version}"
+
+  spec.add_dependency 'activesupport', '~> 6.0'
+  spec.add_dependency 'amazing_print', '~> 1.1'
+  spec.add_dependency 'lograge', '~> 0.11'
+  spec.add_dependency 'ougai', '~> 1.8'
+
+  spec.add_development_dependency 'brakeman', '~> 4.9'
+  spec.add_development_dependency 'bundle-audit', '~> 0.1'
+  spec.add_development_dependency 'ci_reporter_rspec', '~> 1.0'
+  spec.add_development_dependency 'colorize', '~> 0.8'
+  spec.add_development_dependency 'dotenv', '~> 2.7'
+  spec.add_development_dependency 'irb', '~> 1.2' # workaroundfor https://github.com/bundler/bundler/issues/6929
+  spec.add_development_dependency 'listen', '>= 3.0.5', '< 3.2'
+  spec.add_development_dependency 'rails', '~> 6.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec-support', '~> 3.9'
+  spec.add_development_dependency 'rubocop', '~> 0.91.0'
+  spec.add_development_dependency 'simplecov', '~> 0.21.1'
+  spec.add_development_dependency 'simplecov-console', '~> 0.9.1'
+  spec.add_development_dependency 'simplecov-rcov', '~> 0.2'
+end

data/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  gem:
+    build:
+      context: .
+      target: development
+    ports:
+      - target: 3000
+        published: 3000
+    restart: always
+    volumes:
+      # Note that this mounts the *entire* repo directory (including
+      # files ignored in .dockerignore when building the image)
+      - ./:/opt/app
+
+version: "3.7"

data/lib/berkeley_library/logging.rb

@@ -0,0 +1,38 @@
+if defined?(Rails)
+  require 'berkeley_library/logging/railtie'
+else
+  require 'berkeley_library/logging/configurator'
+end
+
+module BerkeleyLibrary
+  # Include this module to get access to a shared global logger.
+  module Logging
+    def logger
+      Logging.logger
+    end
+
+    def logger=(v)
+      Logging.logger = v
+    end
+
+    class << self
+      def logger
+        @logger ||= BerkeleyLibrary::Logging::Loggers.default_logger
+      end
+
+      def logger=(v)
+        @logger = (ensure_logger(v) unless v.nil?)
+      end
+
+      private
+
+      LOG_METHODS = %i[debug info warn error].freeze
+
+      def ensure_logger(v)
+        return v if (missing = LOG_METHODS.reject { |m| v.respond_to?(m) }).empty?
+
+        raise ArgumentError, "Not a logger: #{v.inspect} does not respond to #{missing.join(', ')}"
+      end
+    end
+  end
+end

data/lib/berkeley_library/logging/configurator.rb

@@ -0,0 +1,41 @@
+require 'berkeley_library/logging/env'
+require 'berkeley_library/logging/events'
+require 'berkeley_library/logging/formatters'
+require 'berkeley_library/logging/loggers'
+
+module BerkeleyLibrary
+  module Logging
+    class Configurator
+      class << self
+
+        def configure(config)
+          configure_lograge(config)
+
+          logger = Loggers.new_default_logger(config)
+          logger.info("Custom logger initialized for environment #{Logging.env.inspect}")
+          configure_webpacker(logger)
+          config.logger = logger
+        end
+
+        private
+
+        def configure_lograge(config)
+          return unless config.respond_to?(:lograge)
+
+          config.lograge.tap do |lograge|
+            lograge.enabled = true
+            lograge.custom_options = Events.extract_data_for_lograge
+            lograge.formatter = Formatters.lograge_formatter
+          end
+        end
+
+        def configure_webpacker(logger)
+          return unless defined?(::Webpacker)
+
+          logger.info('Using custom logger for Webpacker')
+          ::Webpacker::Instance.logger = logger
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/logging/env.rb

@@ -0,0 +1,38 @@
+require 'active_support/string_inquirer'
+
+module BerkeleyLibrary
+  module Logging
+    class << self
+      FALLBACK_ENV = 'development'.freeze
+      ENV_PREDICATES = %i[production? test? development?].freeze
+      private_constant :ENV_PREDICATES
+
+      def env
+        return Rails.env if defined?(Rails)
+
+        @env ||= begin
+          # Note: can't just self.env= b/c it returns the wrong value -- see
+          # https://stackoverflow.com/q/65226532/27358
+          env = (ENV['RAILS_ENV'] || ENV['RACK_ENV'] || FALLBACK_ENV)
+          ensure_rails_env_like(env)
+        end
+      end
+
+      def env=(v)
+        if defined?(Rails)
+          Rails.env = v
+        else
+          @env = ensure_rails_env_like(v)
+        end
+      end
+
+      private
+
+      def ensure_rails_env_like(v)
+        return v if ENV_PREDICATES.all? { |p| v.respond_to?(p) }
+
+        ActiveSupport::StringInquirer.new(v)
+      end
+    end
+  end
+end

data/lib/berkeley_library/logging/events.rb

@@ -0,0 +1,39 @@
+module BerkeleyLibrary
+  module Logging
+    module Events
+      class << self
+        def extract_data_for_lograge
+          ->(event) { extract_event_data(event) }
+        end
+
+        private
+
+        def extract_event_data(event)
+          event_data = { time: Time.now }
+          extracted_headers = extract_headers(event)
+          event_data.merge(extracted_headers)
+        end
+
+        def extract_headers(event)
+          return {} unless (headers = event.payload[:headers])
+
+          extracted_headers = {
+            # yes, RFC 2616 uses a variant spelling for 'referrer', it's a known issue
+            # https://tools.ietf.org/html/rfc2616#section-14.36
+            referer: headers['HTTP_REFERER'],
+            request_id: headers['action_dispatch.request_id'],
+            remote_ip: headers['action_dispatch.remote_ip'],
+            remote_addr: headers['REMOTE_ADDR'],
+            x_forwarded_for: headers['HTTP_X_FORWARDED_FOR'],
+            forwarded: headers['HTTP_FORWARDED'] # RFC 7239
+          }
+
+          # Some of these 'headers' include recursive structures
+          # that cause SystemStackErrors in JSON serialization,
+          # so we convert them all to strings
+          extracted_headers.transform_values(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/logging/formatters.rb

@@ -0,0 +1,54 @@
+require 'ougai'
+
+module BerkeleyLibrary
+  module Logging
+    module Formatters
+
+      class << self
+        def new_json_formatter
+          Bunyan.new
+        end
+
+        def new_readable_formatter
+          Ougai::Formatters::Readable.new
+        end
+
+        def lograge_formatter
+          ->(data) { { msg: 'Request', request: Formatters.ensure_hash(data) } }
+        end
+
+        def ensure_hash(message)
+          return {} unless message
+          return message if message.is_a?(Hash)
+
+          { msg: message }
+        end
+      end
+
+      # ------------------------------------------------------------
+      # Private helper classes
+
+      class Bunyan < Ougai::Formatters::Bunyan
+        include Ougai::Logging::Severity
+
+        def _call(severity, time, progname, data)
+          original_data = Formatters.ensure_hash(data)
+
+          # Ougai::Formatters::Bunyan replaces the human-readable severity string
+          # with a numeric level, so we add it here as a separate attribute
+          severity = ensure_human_readable(severity)
+          merged_data = { severity: severity }.merge(original_data)
+          super(severity, time, progname, merged_data)
+        end
+
+        def ensure_human_readable(severity)
+          return to_label(severity) if severity.is_a?(Integer)
+
+          severity.to_s
+        end
+      end
+
+      private_constant :Bunyan
+    end
+  end
+end

data/lib/berkeley_library/logging/logger.rb

@@ -0,0 +1,12 @@
+require 'active_support/logger'
+require 'ougai'
+require 'berkeley_library/logging/tagged_logging_extensions'
+
+module BerkeleyLibrary
+  module Logging
+    class Logger < Ougai::Logger
+      include ActiveSupport::LoggerThreadSafeLevel
+      include ActiveSupport::LoggerSilence
+    end
+  end
+end

data/lib/berkeley_library/logging/loggers.rb

@@ -0,0 +1,79 @@
+require 'berkeley_library/logging/env'
+require 'berkeley_library/logging/formatters'
+require 'berkeley_library/logging/logger'
+
+module BerkeleyLibrary
+  module Logging
+    module Loggers
+      class << self
+        FALLBACK_LOG_DIR = 'log'.freeze
+
+        def default_logger
+          if defined?(Rails)
+            return Rails.logger if Rails.logger
+
+            warn('Rails is defined, but Rails logger is nil')
+          end
+
+          new_default_logger
+        end
+
+        # TODO: support passing a hash / passing default_log_file
+        def new_default_logger(config = nil)
+          return new_readable_logger($stdout) unless config
+          return new_json_logger($stdout) if Logging.env.production?
+          return rails_file_logger(config) if Logging.env.test?
+          return new_broadcast_logger(config) if Logging.env.development?
+
+          raise ArgumentError, "Can't create logger for environment: #{Logging.env.inspect}"
+        end
+
+        def new_json_logger(logdev)
+          new_logger_with(logdev: logdev, formatter: Formatters.new_json_formatter)
+        end
+
+        def new_readable_logger(logdev)
+          new_logger_with(logdev: logdev, formatter: Formatters.new_readable_formatter)
+        end
+
+        private
+
+        def new_broadcast_logger(config)
+          new_json_logger($stdout).tap do |json_logger|
+            file_logger = rails_file_logger(config)
+            json_logger.extend Ougai::Logger.broadcast(file_logger)
+          end
+        end
+
+        def rails_file_logger(config)
+          log_file = default_log_file_for(config)
+          new_readable_logger(log_file)
+        end
+
+        def new_logger_with(logdev:, formatter:)
+          Logger.new(logdev).tap { |l| l.formatter = formatter }
+        end
+
+        def default_log_file_for(config)
+          return config.default_log_file if config.respond_to?(:default_log_file)
+
+          File.join(ensure_log_directory, "#{Logging.env}.log")
+        end
+
+        def ensure_log_directory
+          File.join(workdir, FALLBACK_LOG_DIR).tap do |log_dir|
+            FileUtils.mkdir(log_dir) unless File.exist?(log_dir)
+            raise ArgumentError, "Not a directory: #{log_dir}" unless File.directory?(log_dir)
+          end
+        end
+
+        def workdir
+          return Rails.application.root if defined?(Rails)
+
+          Pathname.getwd
+        end
+
+      end
+    end
+  end
+end

data/lib/berkeley_library/logging/module_info.rb

@@ -0,0 +1,16 @@
+module BerkeleyLibrary
+  module Logging
+    class ModuleInfo
+      NAME = 'berkeley_library-logging'.freeze
+      AUTHOR = 'David Moles'.freeze
+      AUTHOR_EMAIL = 'dmoles@berkeley.edu'.freeze
+      SUMMARY = 'Opinionated Ruby/Rails logging for UC Berkeley Library'.freeze
+      DESCRIPTION = 'A gem providing shared logging code for UC Berkeley Library gems and Rails applications'.freeze
+      LICENSE = 'MIT'.freeze
+      VERSION = '0.2.0'.freeze
+      HOMEPAGE = 'https://github.com/BerkeleyLibrary/logging'.freeze
+
+      private_class_method :new
+    end
+  end
+end

data/lib/berkeley_library/logging/railtie.rb

@@ -0,0 +1,15 @@
+require 'lograge'
+require 'lograge/railtie' # NOTE: registers Lograge::Railtie by side effect
+require 'berkeley_library/logging/configurator'
+
+module BerkeleyLibrary
+  module Logging
+    class Railtie < Rails::Railtie
+      # Don't use the Railtie's own `config` because configure() needs
+      # Rails::Application::Configuration#default_log_file
+      initializer('logging.configure_berkeley_library_logging', before: :initialize_logger) do |app|
+        Configurator.configure(app.config)
+      end
+    end
+  end
+end

data/lib/berkeley_library/logging/tagged_logging_extensions.rb

@@ -0,0 +1,21 @@
+require 'active_support/tagged_logging'
+require 'berkeley_library/logging/formatters'
+
+# Monkey-patch ActiveSupport::TaggedLogging::Formatter
+# not to produce garbage by prepending tags to hashes.
+#
+# TODO: Can we intercept Formatter.extend() instead? See
+# https://github.com/rails/rails/blob/v6.0.3.4/activesupport/lib/active_support/tagged_logging.rb#L73
+module ActiveSupport
+  module TaggedLogging
+    module Formatter
+      def call(severity, time, progname, data)
+        return super unless current_tags.present?
+
+        original_data = BerkeleyLibrary::Logging::Formatters.ensure_hash(data)
+        merged_data = { tags: current_tags }.merge(original_data)
+        super(severity, time, progname, merged_data)
+      end
+    end
+  end
+end