canonical_log 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9fa4e04f9113d21ee261935a7640d755f2e214bbb270b5b13a0edaa701c79afc
+  data.tar.gz: d6ba73178b27401e019ab2b884dd291e870e041fd3a79cf6362913b7c3812497
+SHA512:
+  metadata.gz: b020eafa421cda0eae82281f78a4eb2a58818ab2bb1f2455cc61e806312daf63e83967a44a7ec7716514988a88e3f06ef525574e63bc53edbae1b3c8deb6e19f
+  data.tar.gz: 5813f35498dba878fb721cdfc83e4f71cbef68f977d4e43bf8965040b10577188477b14f280f92195908b727f5e0a9fe65f3e239e9a6d03597e9a5018c9520b0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Krzysztof Duda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/canonical_log/configuration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  class Configuration
+    attr_accessor :sinks, :param_filter_keys, :slow_query_threshold_ms,
+                  :user_context, :before_emit, :ignored_paths,
+                  :sample_rate, :slow_request_threshold_ms, :sampling
+
+    def initialize
+      @sinks = :auto
+      @param_filter_keys = %w[password password_confirmation token secret]
+      @slow_query_threshold_ms = 100.0
+      @user_context = nil
+      @before_emit = nil
+      @ignored_paths = []
+      @sample_rate = 1.0            # Log everything by default
+      @slow_request_threshold_ms = 2000.0
+      @sampling = nil               # Custom sampling proc, receives (event_hash, config) -> bool
+    end
+
+    def resolved_sinks
+      case @sinks
+      when :auto
+        [CanonicalLog::Sinks::Stdout.new]
+      when Array
+        @sinks
+      else
+        [@sinks]
+      end
+    end
+
+    def should_sample?(event_hash)
+      if @sampling
+        @sampling.call(event_hash, self)
+      elsif @sample_rate >= 1.0
+        true
+      else
+        Sampling.default(event_hash, self)
+      end
+    end
+  end
+end

data/lib/canonical_log/context.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Context
+    THREAD_KEY = :canonical_log_event
+
+    def self.init!
+      Thread.current[THREAD_KEY] = Event.new
+    end
+
+    def self.current
+      Thread.current[THREAD_KEY]
+    end
+
+    def self.clear!
+      Thread.current[THREAD_KEY] = nil
+    end
+  end
+end

data/lib/canonical_log/event.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module CanonicalLog
+  class Event
+    CATEGORIES = %i[user business infra service].freeze
+
+    def initialize
+      @fields = {}
+      @categories = {}
+      @mutex = Mutex.new
+      @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def add(hash)
+      @mutex.synchronize do
+        @fields.merge!(hash)
+      end
+    end
+
+    def set(key, value)
+      @mutex.synchronize do
+        @fields[key.to_sym] = value
+      end
+    end
+
+    def increment(key, by = 1)
+      @mutex.synchronize do
+        @fields[key.to_sym] = (@fields[key.to_sym] || 0) + by
+      end
+    end
+
+    def append(key, value)
+      @mutex.synchronize do
+        @fields[key.to_sym] ||= []
+        @fields[key.to_sym] << value
+      end
+    end
+
+    # Categorized context: event.context(:user, id: 123, tier: "premium")
+    def context(category, data)
+      raise ArgumentError, "Unknown category: #{category}" unless CATEGORIES.include?(category.to_sym)
+
+      @mutex.synchronize do
+        @categories[category.to_sym] ||= {}
+        @categories[category.to_sym].merge!(data)
+      end
+    end
+
+    # Structured error capture
+    def add_error(error, metadata = {})
+      @mutex.synchronize do
+        @fields[:error] = {
+          class: error.class.name,
+          message: error.message
+        }.merge(metadata)
+      end
+    end
+
+    def duration_ms
+      elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
+      (elapsed * 1000).round(2)
+    end
+
+    def to_h
+      @mutex.synchronize do
+        result = { timestamp: Time.now.utc.iso8601(3), duration_ms: duration_ms }
+        result.merge!(@fields)
+        @categories.each { |cat, data| result[cat] = data unless data.empty? }
+        result
+      end
+    end
+
+    def to_json(*_args)
+      to_h.to_json
+    end
+  end
+end

data/lib/canonical_log/integrations/error_enrichment.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module CanonicalLog
+  module Integrations
+    module ErrorEnrichment
+      extend ActiveSupport::Concern
+
+      included do
+        around_action :capture_errors_for_canonical_log
+      end
+
+      private
+
+      def capture_errors_for_canonical_log
+        yield
+      rescue StandardError => e
+        CanonicalLog.add(
+          rescued_error_class: e.class.name,
+          rescued_error_message: e.message
+        )
+        raise
+      end
+    end
+  end
+end

data/lib/canonical_log/integrations/sidekiq.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Integrations
+    class Sidekiq
+      def call(_job_instance, msg, queue)
+        Context.init!
+        event = Context.current
+        event.add(
+          job_class: msg['class'],
+          queue: queue,
+          jid: msg['jid']
+        )
+
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        event&.add(
+          error_class: e.class.name,
+          error_message: e.message
+        )
+        raise
+      ensure
+        emit!
+        Context.clear!
+      end
+
+      private
+
+      def emit!
+        event = Context.current
+        return unless event
+
+        config = CanonicalLog.configuration
+        config.before_emit&.call(event)
+        json = event.to_json
+
+        config.resolved_sinks.each do |sink|
+          sink.write(json)
+        rescue StandardError => e
+          warn "[CanonicalLog] Sink error (#{sink.class}): #{e.message}"
+        end
+      rescue StandardError => e
+        warn "[CanonicalLog] Emit error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/canonical_log/middleware.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return @app.call(env) if ignored_path?(env)
+
+      Context.init!
+      seed_request_fields(env)
+
+      status, headers, body = @app.call(env)
+      Context.current&.set(:http_status, status)
+      enrich_user_context(env)
+      [status, headers, body]
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      Context.current&.add_error(e)
+      Context.current&.set(:http_status, 500)
+      raise
+    ensure
+      emit! if Context.current
+      Context.clear!
+    end
+
+    private
+
+    def seed_request_fields(env)
+      event = Context.current
+      return unless event
+
+      request_id = env['action_dispatch.request_id'] ||
+                   env['HTTP_X_REQUEST_ID'] ||
+                   SecureRandom.uuid
+
+      event.add(
+        request_id: request_id,
+        http_method: env['REQUEST_METHOD'],
+        path: env['PATH_INFO'],
+        query_string: env['QUERY_STRING'].to_s.empty? ? nil : env['QUERY_STRING'],
+        remote_ip: env['HTTP_X_FORWARDED_FOR'] || env['REMOTE_ADDR'],
+        user_agent: env['HTTP_USER_AGENT'],
+        content_type: env['CONTENT_TYPE']
+      )
+    end
+
+    def enrich_user_context(env)
+      event = Context.current
+      return unless event
+
+      config = CanonicalLog.configuration
+      if config.user_context
+        begin
+          user_fields = config.user_context.call(env)
+          event.add(user_fields) if user_fields.is_a?(Hash)
+        rescue StandardError => e
+          warn "[CanonicalLog] user_context error: #{e.message}"
+        end
+      elsif defined?(Warden::Manager) && env['warden']
+        user = env['warden'].user rescue nil
+        if user
+          event.context(:user, id: user.try(:id), email: user.try(:email))
+        end
+      end
+    end
+
+    def emit!
+      event = Context.current
+      return unless event
+
+      config = CanonicalLog.configuration
+      config.before_emit&.call(event)
+
+      event_hash = event.to_h
+      return unless config.should_sample?(event_hash)
+
+      json = event_hash.to_json
+
+      config.resolved_sinks.each do |sink|
+        sink.write(json)
+      rescue StandardError => e
+        warn "[CanonicalLog] Sink error (#{sink.class}): #{e.message}"
+      end
+    rescue StandardError => e
+      warn "[CanonicalLog] Emit error: #{e.message}"
+    end
+
+    def ignored_path?(env)
+      path = env['PATH_INFO']
+      CanonicalLog.configuration.ignored_paths.any? do |pattern|
+        case pattern
+        when Regexp then pattern.match?(path)
+        when String then path.start_with?(pattern)
+        end
+      end
+    end
+  end
+end

data/lib/canonical_log/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  class Railtie < Rails::Railtie
+    initializer 'canonical_log.insert_middleware' do |app|
+      app.middleware.insert(0, CanonicalLog::Middleware)
+    end
+
+    initializer 'canonical_log.subscribe' do
+      CanonicalLog::Subscribers::ActionController.subscribe!
+      CanonicalLog::Subscribers::ActiveRecord.subscribe!
+    end
+  end
+end

data/lib/canonical_log/sampling.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Sampling
+    # Default sampling: always keep errors and slow requests, sample the rest.
+    def self.default(event_hash, config)
+      status = event_hash[:http_status] || 0
+      duration = event_hash[:duration_ms] || 0
+
+      # Always keep errors
+      return true if status >= 500
+      return true if event_hash[:error]
+
+      # Always keep slow requests
+      return true if duration >= config.slow_request_threshold_ms
+
+      # Sample the rest
+      rand < config.sample_rate
+    end
+  end
+end

data/lib/canonical_log/sinks/base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Sinks
+    # Duck-type interface for sinks.
+    # Any object responding to #write(json_string) can be used as a sink.
+    class Base
+      def write(json_string)
+        raise NotImplementedError, "#{self.class} must implement #write"
+      end
+    end
+  end
+end

data/lib/canonical_log/sinks/rails_logger.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Sinks
+    class RailsLogger < Base
+      def write(json_string)
+        Rails.logger.info(json_string)
+      end
+    end
+  end
+end

data/lib/canonical_log/sinks/stdout.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Sinks
+    class Stdout < Base
+      def write(json_string)
+        $stdout.puts(json_string)
+      end
+    end
+  end
+end

data/lib/canonical_log/subscribers/action_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Subscribers
+    module ActionController
+      def self.subscribe!
+        ActiveSupport::Notifications.subscribe('process_action.action_controller') do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          handle(event)
+        end
+      end
+
+      def self.handle(notification)
+        event = Context.current
+        return unless event
+
+        payload = notification.payload
+        config = CanonicalLog.configuration
+
+        params = (payload[:params] || {}).except('controller', 'action')
+        filtered_params = filter_params(params, config.param_filter_keys)
+
+        event.add(
+          controller: payload[:controller],
+          action: payload[:action],
+          format: payload[:format],
+          params: filtered_params,
+          view_runtime_ms: payload[:view_runtime]&.round(2),
+          db_runtime_ms: payload[:db_runtime]&.round(2)
+        )
+      end
+
+      def self.filter_params(params, filter_keys)
+        params.each_with_object({}) do |(key, value), filtered|
+          filtered[key] = if filter_keys.include?(key.to_s)
+                            '[FILTERED]'
+                          elsif value.is_a?(Hash)
+                            filter_params(value, filter_keys)
+                          else
+                            value
+                          end
+        end
+      end
+    end
+  end
+end

data/lib/canonical_log/subscribers/active_record.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  module Subscribers
+    module ActiveRecord
+      def self.subscribe!
+        ActiveSupport::Notifications.subscribe('sql.active_record') do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          handle(event)
+        end
+      end
+
+      def self.handle(notification)
+        event = Context.current
+        return unless event
+
+        payload = notification.payload
+        return if %w[SCHEMA CACHE].include?(payload[:name])
+
+        duration_ms = notification.duration
+        event.increment(:db_query_count)
+        event.increment(:db_total_time_ms, duration_ms.round(2))
+
+        threshold = CanonicalLog.configuration.slow_query_threshold_ms
+        return unless duration_ms >= threshold
+
+        event.append(:slow_queries, {
+                       sql: payload[:sql]&.slice(0, 500),
+                       duration_ms: duration_ms.round(2),
+                       name: payload[:name]
+                     })
+      end
+    end
+  end
+end

data/lib/canonical_log/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CanonicalLog
+  VERSION = '0.1.0'
+end

data/lib/canonical_log.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'active_support'
+
+require_relative 'canonical_log/version'
+require_relative 'canonical_log/configuration'
+require_relative 'canonical_log/sampling'
+require_relative 'canonical_log/event'
+require_relative 'canonical_log/context'
+require_relative 'canonical_log/middleware'
+require_relative 'canonical_log/sinks/base'
+require_relative 'canonical_log/sinks/stdout'
+require_relative 'canonical_log/sinks/rails_logger'
+require_relative 'canonical_log/subscribers/action_controller'
+require_relative 'canonical_log/subscribers/active_record'
+
+require_relative 'canonical_log/railtie' if defined?(Rails::Railtie)
+
+module CanonicalLog
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    # Convenience delegations to current event
+    def add(hash)
+      Context.current&.add(hash)
+    end
+
+    def set(key, value)
+      Context.current&.set(key, value)
+    end
+
+    def increment(key, by = 1)
+      Context.current&.increment(key, by)
+    end
+
+    def append(key, value)
+      Context.current&.append(key, value)
+    end
+
+    # Categorized context: CanonicalLog.context(:user, id: 123)
+    def context(category, data)
+      Context.current&.context(category, data)
+    end
+
+    # Structured error: CanonicalLog.add_error(exception)
+    def add_error(error, metadata = {})
+      Context.current&.add_error(error, metadata)
+    end
+  end
+end

data/lib/generators/canonical_log/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module CanonicalLog
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a CanonicalLog initializer in config/initializers'
+
+      def copy_initializer
+        template 'canonical_log.rb', 'config/initializers/canonical_log.rb'
+      end
+    end
+  end
+end

data/lib/generators/canonical_log/templates/canonical_log.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+CanonicalLog.configure do |config|
+  # Sinks determine where the canonical log line is written.
+  # :auto uses RailsLogger in development, Stdout in production.
+  # config.sinks = :auto
+  # config.sinks = [CanonicalLog::Sinks::Stdout.new]
+  # config.sinks = [CanonicalLog::Sinks::RailsLogger.new]
+
+  # Parameter keys to filter from log output (replaced with [FILTERED]).
+  # config.param_filter_keys = %w[password password_confirmation token secret]
+
+  # SQL queries slower than this threshold (in ms) are captured individually.
+  # config.slow_query_threshold_ms = 100.0
+
+  # Proc to extract user context from the controller notification.
+  # Receives an ActiveSupport::Notifications::Event and should return a Hash.
+  # config.user_context = ->(notification) {
+  #   controller = notification.payload[:headers]&.env&.dig("action_controller.instance")
+  #   if controller&.respond_to?(:current_user) && controller.current_user
+  #     { user_id: controller.current_user.id }
+  #   else
+  #     {}
+  #   end
+  # }
+
+  # Hook called with the Event just before it is serialized and emitted.
+  # config.before_emit = ->(event) {
+  #   event.set(:app_version, ENV["APP_VERSION"])
+  # }
+
+  # Paths to ignore (no canonical log line will be emitted).
+  # Supports strings (prefix match) and regexps.
+  # config.ignored_paths = ["/health", "/assets", %r{\A/packs}]
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: canonical_log
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Krzysztof Duda
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Implements the canonical log lines / wide events pattern. Accumulates
+  context throughout a request lifecycle and emits a single structured JSON log line
+  containing everything interesting.
+email:
+- hello@krzysztof.studio
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- lib/canonical_log.rb
+- lib/canonical_log/configuration.rb
+- lib/canonical_log/context.rb
+- lib/canonical_log/event.rb
+- lib/canonical_log/integrations/error_enrichment.rb
+- lib/canonical_log/integrations/sidekiq.rb
+- lib/canonical_log/middleware.rb
+- lib/canonical_log/railtie.rb
+- lib/canonical_log/sampling.rb
+- lib/canonical_log/sinks/base.rb
+- lib/canonical_log/sinks/rails_logger.rb
+- lib/canonical_log/sinks/stdout.rb
+- lib/canonical_log/subscribers/action_controller.rb
+- lib/canonical_log/subscribers/active_record.rb
+- lib/canonical_log/version.rb
+- lib/generators/canonical_log/install_generator.rb
+- lib/generators/canonical_log/templates/canonical_log.rb
+homepage: https://github.com/krzysztoff1/canonical_log
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: One structured JSON log line per request
+test_files: []