logsy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eee92d3c7715964e65bd1a5f5efb80e07328bd8fdf3de735d07664c429f19623
+  data.tar.gz: 3a5a149095b25d6cb00e662f96c5d235c1e35dcb1e728f9977676a49ed039e6b
+SHA512:
+  metadata.gz: 6035309f83d88ad2a07745d01331d38ecff83254685e9b76d204de8f65b2cba0e86246b192dea878ee1231b8e7f98a0d435cd0d80166e1f37422046ab588db2a
+  data.tar.gz: 2fd3061b4df673dd3bc186d0f61bc4e4ac945de8d1f45a6b1d4cf24025f95db834a65a3e453e6aefdc088bcc079a06c0fe60e2635a2b510e830449dcee470a6d

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1.0] - Unreleased
+
+- Initial release.
+- `Logsy[]` / `Logsy[]=` / `Logsy.tags` dictionary-style API for per-request tags — no subclass required.
+- `Logsy::JsonFormatter` for structured JSON log output (one line per call, all current tags merged in).
+- `Logsy::ControllerHooks` for Rails request_id capture and wide-event emission.
+- `Logsy::SidekiqMiddleware::Client` / `Server` for Sidekiq context propagation. Sets `Logsy[:job_id]` automatically. No Sidekiq dependency at runtime.
+- Default `ignored_caller_paths` covers Logger, ActiveSupport, lograge, sprockets, quiet_assets, and Logsy itself.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ruby_is_love
+
+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/README.md

@@ -0,0 +1,199 @@
+# Logsy
+
+Tagged structured logging for Rails apps. JSON output, one line per log call.
+
+Logsy gives you **one wide JSON event per request** plus **correlated breadcrumb logs**, all tagged with whatever per-request context you set via `Logsy[:key] = value`. Tags propagate across background jobs (Sidekiq middleware bundled). Where you ship the JSON is your call — Logsy just writes structured lines to stdout.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'logsy'
+```
+
+```bash
+bundle install
+```
+
+## Usage
+
+### 1. Wire up the JSON formatter
+
+```ruby
+# config/environments/production.rb
+config.logger = ActiveSupport::Logger.new($stdout)
+  .tap { |l| l.formatter = Logsy::JsonFormatter.new }
+```
+
+### 2. Include the controller hooks
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  include Logsy::ControllerHooks
+end
+```
+
+This gives you:
+- `Logsy[:request_id]` automatically populated from `request.request_id` (or `X-Request-Id` header) on every request
+- One "wide event" log line at end of each request with `event: "request"`, method, path, controller, action, status, duration_ms, and any error class/message — plus every tag you set during the request
+
+### 3. Set tags wherever they become known
+
+```ruby
+# In a controller, model, service, anywhere:
+def create
+  order = Order.create!(order_params)
+  Logsy[:order_id] = order.id  # every log from here on includes order_id
+  ...
+end
+```
+
+That's it. No `Current` model to define, no attribute declarations — just key/value.
+
+### 4. (Optional) Background job propagation
+
+If you use Sidekiq:
+
+```ruby
+# config/initializers/sidekiq.rb
+require 'logsy/sidekiq_middleware'
+
+Sidekiq.configure_client do |config|
+  config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
+end
+
+Sidekiq.configure_server do |config|
+  config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
+  config.server_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Server) }
+end
+```
+
+```ruby
+# config/initializers/logsy.rb (optional — only if you want to propagate more than request_id)
+Logsy.configure do |c|
+  c.job_propagated_keys = %i[request_id user_id tenant_id]
+end
+```
+
+The bundled middleware:
+- **Client side**: when a job is enqueued, copies the configured tags from `Logsy[]` into the job payload
+- **Server side**: when the job runs, sets those tags back in `Logsy[]` AND sets `Logsy[:job_id] = job['jid']` automatically
+
+Anything the job code writes via `Logsy[:foo] = bar` while running shows up on every log line emitted during the job. Tags reset automatically after each job (no leak between jobs sharing a worker thread).
+
+For other job systems (Resque, GoodJob, custom), write your own middleware using the same pattern — Logsy's `[]=` / `[]` / `tags` / `reset` API is generic.
+
+## What it looks like in your logs
+
+A regular log line:
+
+```json
+{
+  "ts":"2026-05-02T10:00:00.123Z",
+  "level":"INFO",
+  "msg":"Calling SPG gateway",
+  "file":"app/lib/gateways/spg_gateway.rb",
+  "line":437,
+  "request_id":"abc-123",
+  "user_id":"u-1",
+  "message_id":"m-42",
+  "order_id":"o-9"
+}
+```
+
+The wide event at end of request:
+
+```json
+{
+  "ts":"2026-05-02T10:00:00.250Z",
+  "level":"INFO",
+  "event":"request",
+  "method":"POST",
+  "path":"/v1/orders",
+  "controller":"orders",
+  "action":"create",
+  "status":201,
+  "duration_ms":127.34,
+  "request_id":"abc-123",
+  "user_id":"u-1",
+  "message_id":"m-42",
+  "order_id":"o-9",
+}
+```
+
+Search your log store by `message_id` to find every request from that message. Pivot from a request's `request_id` to see every breadcrumb log line emitted while it ran.
+
+## API reference
+
+```ruby
+Logsy[:user_id] = 'u-1'   # set a tag
+Logsy[:user_id]            # read it
+Logsy.tags                 # all tags as a hash
+Logsy.reset                # clear all tags (the controller/middleware do this for you)
+```
+
+Symbol and string keys are equivalent — `Logsy['user_id']` and `Logsy[:user_id]` access the same slot.
+
+## Customizing the wide event
+
+Override `logsy_request_summary_extras` in your controller to add fields:
+
+```ruby
+class ApplicationController < ActionController::API
+  include Logsy::ControllerHooks
+
+  private
+
+  def logsy_request_summary_extras
+    {
+      ip:              request.remote_ip,
+      user_agent:      request.user_agent,
+      idempotency_key: request.headers['Idempotency-Key']
+    }
+  end
+end
+```
+
+## Configuration reference
+
+```ruby
+Logsy.configure do |c|
+  # Tag keys to copy into job payloads at enqueue and read back at execution.
+  # Default: [:request_id]
+  c.job_propagated_keys = %i[request_id user_id tenant_id]
+
+  # Capture caller file:line via Kernel#caller_locations on every log line.
+  # Disable if you measure overhead. Default: true
+  c.include_caller_location = true
+
+  # Regex patterns for caller frames to skip. Defaults already cover Logger,
+  # ActiveSupport, lograge, sprockets, quiet_assets, and Logsy itself.
+  c.ignored_caller_paths += [%r{/my_internal_logger/}]
+
+  # The "event" name on the request summary. Default: "request"
+  c.request_summary_event_name = 'http_request'
+end
+```
+
+## Why Logsy?
+
+Existing options each cover one piece:
+
+- **`tagged_logging`** (ActiveSupport) — push/pop tag stack, doesn't compose with mutable per-request context
+- **`lograge`** — one wide event per request, but doesn't help your in-action `Rails.logger.info(...)` calls
+- **`semantic_logger`** — heavy, opinionated, replaces the whole logger framework
+
+Logsy fills the gap: a small, dictionary-style API (`Logsy[:foo] = bar`) plus a JSON formatter that reads from it on every log line. No subclasses to define, no DSL to learn — just set tags as you discover them.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec       # 34 specs
+bundle exec rubocop     # lint
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/logsy/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Logsy
+  class Configuration
+    DEFAULT_IGNORED_CALLER_PATHS = [
+      %r{/logger\.rb\z},
+      %r{/active_support/(tagged_logging|logger|broadcast_logger|log_subscriber)},
+      %r{/lograge/},
+      %r{/sprockets/},
+      %r{/quiet_assets/},
+      %r{/lib/logsy/}
+    ].freeze
+
+    # Tag keys that should be carried across job boundaries (e.g. when a
+    # background job is enqueued from a web request, the job inherits
+    # these). The middleware that does the actual carrying is job-runner
+    # specific (Logsy ships one for Sidekiq).
+    attr_accessor :job_propagated_keys, :ignored_caller_paths,
+                  :include_caller_location, :request_summary_event_name
+
+    def initialize
+      @job_propagated_keys        = [:request_id]
+      @ignored_caller_paths       = DEFAULT_IGNORED_CALLER_PATHS.dup
+      @include_caller_location    = true
+      @request_summary_event_name = 'request'
+    end
+  end
+end

data/lib/logsy/controller_hooks.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Logsy
+  # Mix into your ApplicationController (or specific controllers) to:
+  #
+  #   1. Capture the request's UUID into Logsy.context.request_id, so every
+  #      log line emitted during the request carries it.
+  #   2. Emit a single "wide event" log line at end of request with the
+  #      method, path, status, duration_ms, controller, action, error, and
+  #      every Current.* attribute that was set during the request.
+  #
+  # Usage:
+  #
+  #   class ApplicationController < ActionController::API
+  #     include Logsy::ControllerHooks
+  #   end
+  #
+  # Override `logsy_request_summary_extras` in your controller to add
+  # custom fields to the wide event:
+  #
+  #   def logsy_request_summary_extras
+  #     { ip: request.remote_ip, user_agent: request.user_agent }
+  #   end
+  module ControllerHooks
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :_logsy_capture_request_id
+      around_action :_logsy_emit_request_summary
+    end
+
+    private
+
+    def _logsy_capture_request_id
+      Logsy[:request_id] = request.request_id || request.headers['X-Request-Id']
+    end
+
+    def _logsy_emit_request_summary
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      error = nil
+      yield
+    rescue StandardError => e
+      error = e
+      raise
+    ensure
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round(2)
+      payload = {
+        event: Logsy.configuration.request_summary_event_name,
+        method: request.request_method,
+        path: request.path,
+        controller: controller_name,
+        action: action_name,
+        status: response&.status,
+        duration_ms:,
+        error: error && "#{error.class}: #{error.message}"
+      }.merge(logsy_request_summary_extras).compact
+
+      Rails.logger.info(payload)
+    end
+
+    # Override in subclasses to add fields to the request summary wide event.
+    def logsy_request_summary_extras
+      {}
+    end
+  end
+end

data/lib/logsy/json_formatter.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logger'
+require 'time'
+
+module Logsy
+  # Logger formatter that emits one JSON object per log call.
+  #
+  # Each line includes:
+  #   - ts:    UTC ISO-8601 timestamp with millis
+  #   - level: severity ('INFO', 'ERROR', ...)
+  #   - msg:   the log message (when message is a String or Exception)
+  #   - file/line: source location of the call (when include_caller_location)
+  #   - any non-nil attributes from the configured Logsy.context
+  #
+  # When the message is a Hash, its keys are merged directly into the
+  # top-level payload (useful for "wide event" emissions like a request
+  # summary). Symbols and strings are accepted as keys.
+  #
+  # Example output:
+  #   {"ts":"2026-05-02T10:00:00.123Z","level":"INFO","msg":"hello",
+  #    "file":"app/controllers/orders_controller.rb","line":34,
+  #    "request_id":"abc-123","user_id":"u-1"}
+  class JsonFormatter < ::Logger::Formatter
+    def call(severity, time, _progname, message)
+      payload = {
+        ts: time.utc.iso8601(3),
+        level: severity
+      }
+
+      add_caller_location!(payload) if Logsy.configuration.include_caller_location
+      merge_context!(payload)
+      merge_message!(payload, message)
+
+      "#{JSON.dump(payload)}\n"
+    rescue StandardError => e
+      fallback_line(severity, time, e)
+    end
+
+    private
+
+    def add_caller_location!(payload)
+      location = caller_locations.find { |loc| user_frame?(loc.path) }
+      return unless location
+
+      payload[:file] = relative_path(location.path)
+      payload[:line] = location.lineno
+    end
+
+    def user_frame?(path)
+      Logsy.configuration.ignored_caller_paths.none? { |pattern| path.match?(pattern) }
+    end
+
+    def relative_path(path)
+      root = defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? "#{Rails.root}/" : nil
+      return path unless root && path.start_with?(root)
+
+      path[root.length..]
+    end
+
+    def merge_context!(payload)
+      Logsy.tags.each do |key, value|
+        next if value.nil?
+
+        payload[key.to_sym] = value
+      end
+    end
+
+    def merge_message!(payload, message)
+      case message
+      when ::String
+        payload[:msg] = message
+      when ::Hash
+        message.each { |k, v| payload[k.to_sym] = v }
+      when ::Exception
+        payload[:msg] = "#{message.class}: #{message.message}"
+      else
+        payload[:msg] = message.inspect
+      end
+    end
+
+    def fallback_line(severity, time, error)
+      safe = {
+        ts: time.utc.iso8601(3),
+        level: severity,
+        msg: 'logsy_formatter_error',
+        error: "#{error.class}: #{error.message}"
+      }
+      "#{JSON.dump(safe)}\n"
+    end
+  end
+end

data/lib/logsy/sidekiq_middleware/client.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Logsy
+  module SidekiqMiddleware
+    # Client-side middleware: captures configured tags from the enqueueing
+    # process (a web request, a console session, another job) and writes
+    # them into the job payload.
+    class Client
+      def call(_worker_class, job, _queue, _redis_pool)
+        Logsy.configuration.job_propagated_keys.each do |key|
+          value = Logsy[key]
+          job[key.to_s] ||= value if value
+        end
+        yield
+      end
+    end
+  end
+end

data/lib/logsy/sidekiq_middleware/server.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Logsy
+  module SidekiqMiddleware
+    # Server-side middleware: reads propagated tags back from the job
+    # payload, sets them on the per-job Logsy store, sets job_id from
+    # Sidekiq's `jid`, and resets the store after the job runs (even on
+    # error) so tags don't leak between jobs sharing a worker thread.
+    #
+    # Anything the job code writes via `Logsy[:foo] = bar` while running
+    # will appear on every log line emitted during the job.
+    class Server
+      def call(_worker_instance, job, _queue)
+        Logsy[:job_id] = job['jid']
+        Logsy.configuration.job_propagated_keys.each do |key|
+          value = job[key.to_s]
+          Logsy[key] = value if value
+        end
+        yield
+      ensure
+        Logsy.reset
+      end
+    end
+  end
+end

data/lib/logsy/sidekiq_middleware.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'logsy/sidekiq_middleware/client'
+require 'logsy/sidekiq_middleware/server'
+
+module Logsy
+  # Sidekiq middleware namespace. Require this file (or rely on a Rails
+  # railtie) to make {Client} and {Server} available, then register them
+  # with Sidekiq:
+  #
+  #   Sidekiq.configure_client do |config|
+  #     config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
+  #   end
+  #
+  #   Sidekiq.configure_server do |config|
+  #     config.client_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Client) }
+  #     config.server_middleware { |chain| chain.add(Logsy::SidekiqMiddleware::Server) }
+  #   end
+  module SidekiqMiddleware
+  end
+end

data/lib/logsy/store.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/current_attributes'
+
+module Logsy
+  # Internal per-request / per-job key-value store. Backed by
+  # ActiveSupport::CurrentAttributes so it is fiber-local and gets reset
+  # automatically by the Rails executor between requests.
+  #
+  # Consumers should not access this class directly — use `Logsy[:key]`,
+  # `Logsy[:key] = value`, `Logsy.tags`, and `Logsy.reset` instead.
+  class Store < ActiveSupport::CurrentAttributes
+    attribute :tags
+
+    def tags
+      super || (self.tags = {})
+    end
+  end
+end

data/lib/logsy/version.rb

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

data/lib/logsy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'logsy/version'
+require 'logsy/store'
+require 'logsy/configuration'
+require 'logsy/json_formatter'
+require 'logsy/controller_hooks'
+
+module Logsy
+  class Error < StandardError; end
+
+  class << self
+    # Read a tag from the per-request store.
+    #
+    #   Logsy[:user_id]   # => 'u-1' or nil
+    def [](key)
+      Store.tags[key.to_sym]
+    end
+
+    # Write a tag into the per-request store. From this point on, every
+    # log line emitted during the current request (or job) carries it.
+    # Non-nil values are coerced to String so log fields have a consistent
+    # type when ingested by structured log stores (which often infer field
+    # type from the first value they see).
+    #
+    #   Logsy[:user_id] = user.id   # 42        -> "42"
+    #   Logsy[:order_id] = nil      # nil stays nil
+    def []=(key, value)
+      Store.tags[key.to_sym] = value&.to_s
+    end
+
+    # All tags currently set, as a hash. Used by the formatter on every
+    # log line; consumers can call it for debugging.
+    def tags
+      Store.tags
+    end
+
+    # Clear all tags. The Rails executor calls this between requests, and
+    # the Sidekiq middleware calls it between jobs. You usually don't need
+    # to call it yourself.
+    def reset
+      Store.reset
+    end
+
+    # Configure the gem. Yields the {Configuration} instance.
+    #
+    #   Logsy.configure do |c|
+    #     c.job_propagated_keys = %i[request_id user_id]
+    #   end
+    def configure
+      yield(configuration)
+      configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Test helper.
+    def reset_configuration!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,126 @@
+--- !ruby/object:Gem::Specification
+name: logsy
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ruby_is_love
+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: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: |
+  Logsy gives Rails apps one wide JSON event per request plus correlated
+  breadcrumb logs, all tagged with whatever per-request context you set
+  via Logsy[:key] = value. Tags propagate across background jobs.
+  Generic JSON output to stdout — bring your own log shipper.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/logsy.rb
+- lib/logsy/configuration.rb
+- lib/logsy/controller_hooks.rb
+- lib/logsy/json_formatter.rb
+- lib/logsy/sidekiq_middleware.rb
+- lib/logsy/sidekiq_middleware/client.rb
+- lib/logsy/sidekiq_middleware/server.rb
+- lib/logsy/store.rb
+- lib/logsy/version.rb
+homepage: https://rubygems.org/profiles/ruby_is_love
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://rubygems.org/profiles/ruby_is_love
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Tagged structured logging for Rails apps with cross-process context propagation
+test_files: []