lognorth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dbd243e69bd9758c158d11868e091edc0f0c629916cebc8094fdcfb74664b0b3
+  data.tar.gz: db2c6d4d5e68353da4ecb2757737595ec144c9ae002202bf3cde5abcacdfa978
+SHA512:
+  metadata.gz: 1381eee25cc094217d00d294ee381846cdb0390110e2e727c104459c5199918ede21c6157b1dfbd723b39d8fde5cc45b74998e031b352df058d76676a437a57e
+  data.tar.gz: 70a5edefba779fd982adcaf91465c34ec89082242428c953485ba4a9855ddb7852f4950c6e01ba21636ac1c2bbfb6963ef66cbbc3208f6594abc85196b1914f7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LogNorth
+
+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,115 @@
+# LogNorth Rails SDK
+
+Send errors and logs from Rails to [LogNorth](https://lognorth.com) for monitoring and alerting.
+
+## Installation
+
+```ruby
+gem "lognorth", github: "karloscodes/lognorth-sdk-rails"
+```
+
+## Rails Setup
+
+Add credentials:
+
+```yaml
+# config/credentials.yml.enc
+lognorth:
+  url: https://your-lognorth-instance.com
+  api_key: your_api_key
+```
+
+That's it. The gem auto-configures via Railtie.
+
+### Manual Configuration
+
+```ruby
+# config/initializers/lognorth.rb
+LogNorth.config(
+  ENV["LOGNORTH_URL"],
+  ENV["LOGNORTH_API_KEY"]
+)
+```
+
+### Options
+
+```ruby
+# config/application.rb
+config.lognorth.enabled = true           # Default: on everywhere except development and test
+config.lognorth.middleware = true        # Log HTTP requests
+config.lognorth.error_subscriber = true  # Report exceptions (Rails 7+)
+
+# Paths to skip from request logging. Defaults to Rails' built-in
+# health-check endpoint; set to [] to log everything or replace with
+# your own list.
+config.lognorth.ignored_paths = ["/up", "/healthz"]
+```
+
+Default: `["/up"]` (Rails 7.1's auto-generated health check — swamped by
+kamal-proxy and load-balancer pings otherwise). Setting `ignored_paths =
+[]` disables ignoring entirely. Matching is exact path or `path/…`
+prefix, so `/up` also covers `/up/detail`.
+
+### Client errors are not errors
+
+An exception that Rails answers with a 4xx is the request's fault, not the app's:
+`ActiveRecord::RecordNotFound` (404), `ActionController::InvalidAuthenticityToken`
+(422), `ActionController::ParameterMissing` (400). The SDK logs the request with
+that status and does not report an error, so these never become issues or alerts.
+
+Rails decides the status from `config.action_dispatch.rescue_responses`, and the SDK
+asks the same map. To report one of them as an error, map it to a 5xx:
+
+```ruby
+config.action_dispatch.rescue_responses["ActiveRecord::RecordNotFound"] = :internal_server_error
+```
+
+## Usage
+
+```ruby
+# Log messages (batched, sent after 5s or at 10 events)
+LogNorth.log("User signed up", { user_id: 123 })
+
+# Report errors (sent at once)
+begin
+  risky_operation
+rescue => e
+  LogNorth.error("Payment failed", e, { order_id: 456 })
+  raise
+end
+
+# Manual flush (called automatically at exit)
+LogNorth.flush
+```
+
+## Batching and delivery
+
+Logging calls never block and never raise. They add the event to a queue in memory.
+One background thread sends the queue, one request at a time.
+
+- The thread sends when the queue holds 10 events, when you report an error, or 5 seconds after the first event.
+- A request holds at most 500 events and 1 MB of JSON.
+- The queue holds at most 10,000 events or 10 MB of JSON.
+- The SDK trims an event to at most 64 KB before it enters the queue. It marks a trimmed event with `context.truncated = true`.
+
+When a send fails, the SDK keeps the events and tries again later. Events keep their order.
+
+- On a network error, a timeout, or a 5xx, it waits 1 second, then 2, then 4, up to 60.
+- On a 429 or 503, it waits as long as the `Retry-After` header says.
+- On a 401, 403, or 404, it waits 60 seconds, then up to 5 minutes. It writes one line to stderr, so you can fix the url or the key.
+- On a 413 or other 4xx, it splits the batch in two and sends again. It drops a single event the server still refuses.
+
+When the queue is full, the SDK drops the oldest event that is not an error. It keeps errors longest.
+After the next successful send, it logs `LogNorth client dropped N events` with the counts.
+
+At exit (including SIGTERM and SIGINT), the SDK sends what is left in the queue for up to 5 seconds.
+It writes the number of events it could not send to stderr.
+
+## Rack (without Rails)
+
+```ruby
+require "lognorth"
+
+LogNorth.config("https://lognorth.example.com", "api_key")
+use LogNorth::Middleware
+```

data/lib/lognorth/active_job_subscriber.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module LogNorth
+  module ActiveJobSubscriber
+    # Carries the trace ID from enqueue time (e.g. during a request)
+    # through to job execution, so the job shares the request's trace.
+    module TraceCarrier
+      def serialize
+        super.merge("lognorth_trace_id" => LogNorth::Client.current_trace_id)
+      end
+
+      def deserialize(job_data)
+        super
+        @lognorth_trace_id = job_data["lognorth_trace_id"]
+      end
+    end
+
+    def self.attach
+      ActiveJob::Base.prepend(TraceCarrier)
+
+      ActiveJob::Base.around_perform do |job, block|
+        trace_id = job.instance_variable_get(:@lognorth_trace_id) || SecureRandom.hex(8)
+        LogNorth::Client.current_trace_id = trace_id
+        started_at = Time.now
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        block.call
+
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        LogNorth::Client.send_event(
+          "#{job.class.name} completed",
+          { job: job.class.name, queue: job.queue_name, job_id: job.job_id },
+          trace_id: trace_id,
+          duration_ms: duration_ms,
+          timestamp: started_at
+        )
+        LogNorth.flush
+        LogNorth::Client.current_trace_id = nil
+      rescue StandardError => e
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        LogNorth::Client.send_error_event(
+          "#{job.class.name} failed", e,
+          { job: job.class.name, queue: job.queue_name, job_id: job.job_id },
+          trace_id: trace_id,
+          duration_ms: duration_ms,
+          timestamp: started_at
+        )
+        LogNorth.flush
+        LogNorth::Client.current_trace_id = nil
+        raise
+      end
+    end
+  end
+end

data/lib/lognorth/client.rb

@@ -0,0 +1,468 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "time"
+require "uri"
+
+module LogNorth
+  MAX_BUFFER = 10_000                 # events in the queue
+  MAX_BUFFER_BYTES = 10 * 1024 * 1024 # JSON bytes in the queue
+  MAX_BATCH = 500                     # events in one request
+  MAX_BATCH_BYTES = 1024 * 1024       # JSON bytes in one request
+  MAX_EVENT_BYTES = 64 * 1024
+  MAX_MESSAGE_CHARS = 1000
+  MAX_STACK_TRACE_BYTES = 16 * 1024
+  MAX_STRING_BYTES = 8 * 1024
+  # The context keys an event keeps when it is still too big after trimming.
+  ESSENTIAL_KEYS = %w[error error_class error_file error_line method path status environment].freeze
+
+  module Client
+    # An event in the queue, with its JSON size and whether it is an error.
+    Entry = Struct.new(:event, :bytes, :error)
+
+    @mutex = Mutex.new
+    @wakeup = ConditionVariable.new
+    # Held for the whole of a send, so only one request is in flight.
+    # Lock order: @send_lock first, then @mutex.
+    @send_lock = Mutex.new
+    @sender = nil
+    @buffer = []      # Entry objects, oldest first
+    @bytes = 0        # sum of the bytes of the entries in @buffer
+    @batch_sizes = [] # sizes of the batches put back at the front
+    @dropped = 0
+    @dropped_errors = 0
+    @first_at = nil   # when the first event entered an empty queue
+    @urgent = false   # send without waiting for the 5-second timer
+    @retry_at = nil   # never send before this time
+    @failing = nil    # nil, :retrying or :config: the state last written to stderr
+    @endpoint = nil
+    @api_key = nil
+    @environment = nil
+
+    # Wait times in seconds. Tests set them lower.
+    @flush_interval = 5
+    @first_backoff = 1
+    @max_backoff = 60
+    @first_config_backoff = 60
+    @max_config_backoff = 300
+    @shutdown_timeout = 5
+    @backoff = @first_backoff
+    @config_backoff = @first_config_backoff
+
+    class << self
+      attr_accessor :debug
+
+      def config(url, key, environment: nil)
+        @mutex.synchronize do
+          @endpoint = url.chomp("/")
+          @api_key = key
+          @environment = environment
+        end
+        log_debug("configured with url=#{url} env=#{environment.inspect}")
+      end
+
+      def configured?
+        @mutex.synchronize { !@endpoint.nil? && !@api_key.nil? }
+      end
+
+      def log(message, context = {})
+        send_event(message, context)
+      end
+
+      def error(message, exception, context = {})
+        send_error_event(message, exception, context)
+      end
+
+      def current_trace_id
+        Thread.current[:lognorth_trace_id]
+      end
+
+      def current_trace_id=(id)
+        Thread.current[:lognorth_trace_id] = id
+      end
+
+      def send_event(message, context = {}, trace_id: nil, duration_ms: nil, timestamp: nil)
+        return unless configured?
+
+        trace_id ||= current_trace_id
+        event = {
+          message: message,
+          timestamp: (timestamp || Time.now).utc.iso8601(3),
+          context: stamp_environment(context)
+        }
+        event[:trace_id] = trace_id if trace_id
+        event[:duration_ms] = duration_ms if duration_ms
+
+        enqueue(event)
+      end
+
+      def send_error_event(message, exception, context = {}, trace_id: nil, duration_ms: nil, timestamp: nil)
+        return unless configured?
+
+        trace_id ||= current_trace_id
+        error_file = ""
+        error_line = 0
+        error_caller = ""
+        if exception.backtrace&.first
+          if (match = exception.backtrace.first.match(/(.+):(\d+):in [`'](.+)'/))
+            error_file = File.basename(match[1])
+            error_line = match[2].to_i
+            error_caller = match[3]
+          end
+        end
+
+        event = {
+          message: message,
+          timestamp: (timestamp || Time.now).utc.iso8601(3),
+          context: stamp_environment(context.merge(
+            error: exception.message,
+            error_class: exception.class.name,
+            error_file: error_file,
+            error_line: error_line,
+            error_caller: error_caller,
+            stack_trace: exception.backtrace&.first(20)&.join("\n")
+          ))
+        }
+        event[:trace_id] = trace_id if trace_id
+        event[:duration_ms] = duration_ms if duration_ms
+
+        enqueue(event, urgent: true)
+      end
+
+      # Sends what is in the queue now, ignoring any backoff. Each batch gets
+      # one attempt, all within the shutdown timeout. Events that could not
+      # be sent stay in the queue. Returns how many events are left.
+      def flush
+        deadline = monotonic + @shutdown_timeout
+        @send_lock.synchronize do
+          loop do
+            left = deadline - monotonic
+            break if left <= 0
+
+            batch = @mutex.synchronize { take_batch }
+            break unless batch
+            break unless deliver(batch, timeout: left)
+          end
+        end
+        @mutex.synchronize { @buffer.size }
+      rescue StandardError => e
+        log_debug("flush failed: #{e.class}: #{e.message}")
+        @mutex.synchronize { @buffer.size }
+      end
+
+      # Called at process exit. Events still queued after the flush are lost.
+      def shutdown
+        left = flush
+        warn("[LogNorth] exiting with #{left} unsent event(s); they are lost") if left.positive?
+      end
+
+      private
+
+      # Adds context.environment when the client was configured with one.
+      # The server displays this on every event/issue/trace so users can tell
+      # which deployment a log came from.
+      def stamp_environment(context)
+        env = @mutex.synchronize { @environment }
+        return context unless env
+
+        context.merge(environment: env)
+      end
+
+      def enqueue(event, urgent: false)
+        entry = new_entry(trim(event))
+        @mutex.synchronize do
+          push(entry)
+          @urgent = true if urgent
+          start_sender
+          @wakeup.signal
+        end
+      rescue StandardError => e
+        log_debug("could not queue event: #{e.class}: #{e.message}")
+      end
+
+      def new_entry(event)
+        Entry.new(event, JSON.generate(event).bytesize, error_event?(event[:context]))
+      end
+
+      def error_event?(context)
+        return false unless context.is_a?(Hash)
+
+        status = fetch(context, :status)
+        !fetch(context, :error).nil? || !fetch(context, :error_class).nil? ||
+          (status.is_a?(Integer) && status >= 500)
+      end
+
+      def fetch(hash, key)
+        hash.key?(key) ? hash[key] : hash[key.to_s]
+      end
+
+      # Cuts an event down to at most MAX_EVENT_BYTES of JSON, so one huge
+      # event cannot fill the queue.
+      def trim(event)
+        trimmed = false
+        if event[:message].is_a?(String) && event[:message].length > MAX_MESSAGE_CHARS
+          event[:message] = event[:message][0, MAX_MESSAGE_CHARS]
+          trimmed = true
+        end
+
+        context = event[:context]
+        if context.is_a?(Hash)
+          context = context.to_h do |key, value|
+            limit = key.to_s == "stack_trace" ? MAX_STACK_TRACE_BYTES : MAX_STRING_BYTES
+            if value.is_a?(String) && value.bytesize > limit
+              trimmed = true
+              [key, value.byteslice(0, limit).scrub("")]
+            else
+              [key, value]
+            end
+          end
+          event[:context] = context
+        end
+
+        if JSON.generate(event).bytesize > MAX_EVENT_BYTES && context.is_a?(Hash)
+          event[:context] = context.select { |key, _| ESSENTIAL_KEYS.include?(key.to_s) }
+          trimmed = true
+        end
+
+        event[:context] = event[:context].merge(truncated: true) if trimmed
+        event
+      end
+
+      # Call with @mutex held. Adds an entry at the back.
+      def push(entry)
+        @first_at ||= monotonic
+        @buffer << entry
+        @bytes += entry.bytes
+        drop_oldest while over_limit?
+      end
+
+      # Call with @mutex held.
+      def over_limit?
+        @buffer.size > MAX_BUFFER || @bytes > MAX_BUFFER_BYTES
+      end
+
+      # Call with @mutex held. Drops the oldest event that is not an error,
+      # or the oldest error when the queue holds nothing else.
+      def drop_oldest
+        index = @buffer.index { |entry| !entry.error } || 0
+        entry = @buffer.delete_at(index)
+        @bytes -= entry.bytes
+        count_drop(entry, "queue full, dropping the oldest events")
+      end
+
+      # Call with @mutex held.
+      def count_drop(entry, reason)
+        warn("[LogNorth] #{reason}") if @dropped.zero?
+        @dropped += 1
+        @dropped_errors += 1 if entry.error
+      end
+
+      # Call with @mutex held. A forked child has no sender thread; this
+      # starts a new one there.
+      def start_sender
+        return if @sender&.alive?
+
+        @sender = Thread.new { run_sender }
+      end
+
+      def run_sender
+        loop do
+          @mutex.synchronize { @wakeup.wait(@mutex, seconds_until_due) until seconds_until_due&.zero? }
+          @send_lock.synchronize do
+            batch = @mutex.synchronize { take_batch if seconds_until_due&.zero? }
+            deliver(batch) if batch
+          end
+        end
+      rescue StandardError => e
+        log_debug("sender stopped: #{e.class}: #{e.message}")
+      end
+
+      # Call with @mutex held. 0 when the queue should be sent now, nil to
+      # wait for a new event, else the seconds left to wait.
+      def seconds_until_due
+        return nil if @buffer.empty?
+
+        now = monotonic
+        return @retry_at - now if @retry_at && now < @retry_at
+        return 0 if @urgent || @buffer.size >= 10 || @bytes > MAX_BUFFER_BYTES / 2
+
+        [@first_at + @flush_interval - now, 0].max
+      end
+
+      # Call with @mutex held. Takes entries from the front, up to MAX_BATCH
+      # events and MAX_BATCH_BYTES of JSON, and always at least one.
+      def take_batch
+        return nil if @buffer.empty?
+
+        max = [@batch_sizes.shift || MAX_BATCH, MAX_BATCH].min
+        count = 0
+        bytes = 12 # {"events":[]}
+        while count < @buffer.size && count < max
+          bytes += @buffer[count].bytes + 1
+          break if bytes > MAX_BATCH_BYTES && count.positive?
+
+          count += 1
+        end
+        batch = @buffer.shift(count)
+        @bytes -= batch.sum(&:bytes)
+        if @buffer.empty?
+          @first_at = nil
+          @urgent = false
+          @batch_sizes.clear
+        end
+        batch
+      end
+
+      # Call with @mutex held. Puts events back at the front, in order. The
+      # next send takes the same events again.
+      def put_back(batch, sizes = [batch.size])
+        @batch_sizes.unshift(*sizes)
+        @buffer = batch + @buffer
+        @bytes += batch.sum(&:bytes)
+        @first_at ||= monotonic
+        @urgent = true
+        drop_oldest while over_limit?
+      end
+
+      # Sends one batch and acts on the answer. Returns true when the next
+      # batch can go out at once.
+      def deliver(batch, timeout: nil)
+        code, retry_after = post(batch, timeout)
+        log_debug("response: #{code}")
+        @mutex.synchronize { handle_answer(batch, code, retry_after) }
+      rescue StandardError => e
+        log_debug("send failed: #{e.class}: #{e.message}")
+        @mutex.synchronize { retry_later(batch, "network error (#{e.class})", wait_with_jitter) }
+      end
+
+      # Call with @mutex held.
+      def handle_answer(batch, code, retry_after)
+        case code
+        when 200..299
+          succeeded
+          true
+        when 429, 503
+          # The server said when; the backoff stays for failures that do not say.
+          retry_later(batch, "server answered #{code}", retry_after || next_backoff)
+        when 408, 500..599
+          retry_later(batch, "server answered #{code}", wait_with_jitter)
+        when 401, 403, 404
+          misconfigured(batch, code)
+        when 400..499
+          reject(batch)
+          true
+        else # a redirect or an unknown answer: most likely a wrong url
+          misconfigured(batch, code)
+        end
+      end
+
+      # Call with @mutex held.
+      def misconfigured(batch, code)
+        retry_later(batch, "server answered #{code}, check the LogNorth url and api key",
+                    next_config_backoff, state: :config)
+      end
+
+      # Call with @mutex held.
+      def succeeded
+        warn("[LogNorth] delivery recovered") if @failing
+        @failing = nil
+        @retry_at = nil
+        @backoff = @first_backoff
+        @config_backoff = @first_config_backoff
+        return if @dropped.zero?
+
+        report = {
+          message: "LogNorth client dropped #{@dropped} events",
+          timestamp: Time.now.utc.iso8601(3),
+          context: stamped({ dropped: @dropped, dropped_errors: @dropped_errors })
+        }
+        @dropped = 0
+        @dropped_errors = 0
+        push(new_entry(report))
+        @urgent = true
+      end
+
+      # Call with @mutex held. The server can never accept this batch as it
+      # is: split it, or drop it when it is a single event.
+      def reject(batch)
+        if batch.size > 1
+          half = (batch.size + 1) / 2
+          put_back(batch, [half, batch.size - half])
+        else
+          count_drop(batch.first, "server rejected an event, dropping it")
+        end
+      end
+
+      # Call with @mutex held. Returns false: the next send must wait.
+      def retry_later(batch, reason, wait, state: :retrying)
+        # The next send takes a full batch again; a refused batch splits again.
+        @batch_sizes.clear
+        put_back(batch, [])
+        @retry_at = monotonic + wait
+        warn("[LogNorth] #{reason}; keeping #{@buffer.size} event(s) and retrying") if @failing != state
+        @failing = state
+        false
+      end
+
+      # Call with @mutex held.
+      def stamped(context)
+        @environment ? context.merge(environment: @environment) : context
+      end
+
+      def next_backoff
+        wait = @backoff
+        @backoff = [@backoff * 2, @max_backoff].min
+        wait
+      end
+
+      def wait_with_jitter
+        next_backoff * rand(0.8..1.2)
+      end
+
+      def next_config_backoff
+        wait = @config_backoff
+        @config_backoff = [@config_backoff * 2, @max_config_backoff].min
+        wait
+      end
+
+      # Returns the status code and the Retry-After seconds (nil when the
+      # header is missing or not an integer).
+      def post(batch, timeout)
+        endpoint, api_key = @mutex.synchronize { [@endpoint, @api_key] }
+        uri = URI("#{endpoint}/api/v1/events/batch")
+        log_debug("sending #{batch.size} event(s) to #{uri}")
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = [5, timeout].compact.min
+        http.read_timeout = [10, timeout].compact.min
+        http.write_timeout = [10, timeout].compact.min
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = "Bearer #{api_key}"
+        request.body = JSON.generate(events: batch.map(&:event))
+
+        response = http.request(request)
+        header = response["Retry-After"]&.strip
+        retry_after = header.to_i.clamp(1, 300) if header&.match?(/\A\d+\z/)
+        [response.code.to_i, retry_after]
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def warn(msg)
+        $stderr.puts msg
+      end
+
+      def log_debug(msg)
+        return unless @debug
+
+        $stdout.puts "[LogNorth] #{msg}"
+      end
+    end
+  end
+end

data/lib/lognorth/error_subscriber.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module LogNorth
+  class ErrorSubscriber
+    def report(error, handled:, severity:, context: {}, source: nil)
+      # Rails answers these with a 4xx (not found, bad CSRF token). The
+      # middleware logs the request with that status; it is not an error.
+      return if LogNorth.client_error?(error)
+
+      ctx = context.dup
+      ctx[:handled] = handled
+      ctx[:severity] = severity
+      ctx[:source] = source if source
+
+      LogNorth.error(error.message, error, ctx)
+    end
+  end
+end

data/lib/lognorth/middleware.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module LogNorth
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      path = env["PATH_INFO"]
+
+      # Skip ignored paths (health checks, metrics, etc.)
+      if ignored_path?(path)
+        return @app.call(env)
+      end
+
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      start_time = Time.now
+      trace_id = env["HTTP_X_TRACE_ID"].to_s.strip
+      trace_id = SecureRandom.hex(8) if trace_id.empty?
+      LogNorth::Client.current_trace_id = trace_id
+
+      status, headers, response = @app.call(env)
+
+      # Don't track requests that didn't match any route (scanner noise)
+      if status == 404 && !env["action_controller.instance"]
+        LogNorth::Client.current_trace_id = nil
+        return [status, headers, response]
+      end
+
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+      headers["X-Trace-ID"] = trace_id
+
+      context = { method: env["REQUEST_METHOD"], path: env["PATH_INFO"], status: status }
+      merge_route_info!(context, env)
+
+      LogNorth::Client.send_event(
+        "#{env['REQUEST_METHOD']} #{env['PATH_INFO']} → #{status}",
+        context,
+        trace_id: trace_id,
+        duration_ms: duration_ms,
+        timestamp: start_time
+      )
+
+      LogNorth.flush if status >= 500
+
+      LogNorth::Client.current_trace_id = nil
+      [status, headers, response]
+    rescue StandardError => e
+      duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+      if LogNorth.client_error?(e)
+        # Rails turns this into a 4xx further out. Log the request with that
+        # status, like any other request, instead of an error.
+        status = LogNorth.response_status_for(e)
+        context = { method: env["REQUEST_METHOD"], path: env["PATH_INFO"], status: status }
+        merge_route_info!(context, env)
+        LogNorth::Client.send_event(
+          "#{env['REQUEST_METHOD']} #{env['PATH_INFO']} → #{status}", context,
+          trace_id: trace_id, duration_ms: duration_ms, timestamp: start_time
+        )
+        LogNorth::Client.current_trace_id = nil
+        raise
+      end
+      LogNorth::Client.send_error_event(
+        "Request failed: #{env['REQUEST_METHOD']} #{env['PATH_INFO']}", e,
+        { method: env["REQUEST_METHOD"], path: env["PATH_INFO"] },
+        trace_id: trace_id,
+        duration_ms: duration_ms,
+        timestamp: start_time
+      )
+      LogNorth::Client.current_trace_id = nil
+      raise
+    end
+
+    private
+
+    def ignored_path?(path)
+      ignored_paths = Rails.application.config.lognorth.ignored_paths rescue []
+      return false if ignored_paths.nil? || ignored_paths.empty?
+
+      ignored_paths.any? { |p| path == p || path.start_with?("#{p}/") }
+    end
+
+    # Rails populates action_controller.instance after dispatch so the
+    # controller/action names — and the named route when available —
+    # can be pulled straight off the env.
+    def merge_route_info!(context, env)
+      controller = env["action_controller.instance"]
+      return unless controller
+
+      klass = controller.class.name
+      action = controller.respond_to?(:action_name) ? controller.action_name : nil
+      context[:controller] = klass if klass
+      context[:action] = action if action
+    end
+  end
+end

data/lib/lognorth/railtie.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module LogNorth
+  class Railtie < Rails::Railtie
+    config.lognorth = ActiveSupport::OrderedOptions.new
+    # nil = auto (production only). Set true/false to override.
+    config.lognorth.enabled = nil
+    config.lognorth.middleware = true
+    config.lognorth.error_subscriber = true
+    config.lognorth.active_job = true
+    # Rails 7.1+ auto-generates /up as a health-check endpoint; kamal-proxy
+    # and most load balancers hit it constantly and it would otherwise swamp
+    # the log feed. Set to [] to disable or pass your own list to replace.
+    config.lognorth.ignored_paths = ["/up"]
+
+    initializer "lognorth.middleware" do |app|
+      if LogNorth::Railtie.lognorth_enabled?(app) && app.config.lognorth.middleware
+        app.middleware.use LogNorth::Middleware
+      end
+    end
+
+    config.after_initialize do |app|
+      next unless LogNorth::Railtie.lognorth_enabled?(app)
+
+      url = app.config.lognorth.url || LogNorth::Railtie.dig_credential(app, :url)
+      key = app.config.lognorth.api_key || LogNorth::Railtie.dig_credential(app, :api_key)
+
+      unless url && key
+        Rails.logger.warn("[LogNorth] enabled but credentials missing — set Rails credentials lognorth.url/api_key or config.lognorth.{url,api_key}")
+        next
+      end
+
+      LogNorth.config(url, key, environment: Rails.env.to_s)
+      LogNorth::Client.debug = false # Rails.env.local? made tests/dev noisy
+
+      if app.config.lognorth.error_subscriber && Rails.version >= "7.0"
+        Rails.error.subscribe(LogNorth::ErrorSubscriber.new)
+      end
+
+      if app.config.lognorth.active_job && defined?(ActiveJob)
+        require "lognorth/active_job_subscriber"
+        LogNorth::ActiveJobSubscriber.attach
+      end
+    end
+
+    class << self
+      # Default off in development and test only. Production, staging, preview,
+      # qa, and any other custom env opt in automatically. Set
+      # config.lognorth.enabled = true/false to override.
+      def lognorth_enabled?(app)
+        explicit = app.config.lognorth.enabled
+        return explicit unless explicit.nil?
+
+        !(Rails.env.development? || Rails.env.test?)
+      end
+
+      def dig_credential(app, key)
+        app.credentials.dig(:lognorth, key)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/lognorth.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "lognorth/client"
+require_relative "lognorth/middleware"
+require_relative "lognorth/error_subscriber"
+require_relative "lognorth/railtie" if defined?(Rails::Railtie)
+
+module LogNorth
+  class << self
+    def config(url, key, environment: nil)
+      Client.config(url, key, environment: environment)
+    end
+
+    def log(message, context = {})
+      Client.log(message, context)
+    end
+
+    def error(message, exception, context = {})
+      Client.error(message, exception, context)
+    end
+
+    def flush
+      Client.flush
+    end
+
+    # The HTTP status Rails answers this exception with, from
+    # config.action_dispatch.rescue_responses. RecordNotFound is a 404,
+    # InvalidAuthenticityToken a 422, anything unmapped a 500. Nil outside Rails.
+    def response_status_for(exception)
+      return nil unless defined?(ActionDispatch::ExceptionWrapper)
+
+      ActionDispatch::ExceptionWrapper.status_code_for_exception(exception.class.name)
+    end
+
+    # A client error is an exception Rails answers with a 4xx: the request
+    # was wrong, the app is fine. It is not reported as an error.
+    def client_error?(exception)
+      status = response_status_for(exception)
+      !status.nil? && status < 500
+    end
+  end
+end
+
+# Ruby runs at_exit on SIGTERM and SIGINT too, unless the app traps them.
+at_exit { LogNorth::Client.shutdown }

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: lognorth
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- LogNorth
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Send errors and logs from Rails to LogNorth for monitoring and alerting
+email:
+- hello@lognorth.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/lognorth.rb
+- lib/lognorth/active_job_subscriber.rb
+- lib/lognorth/client.rb
+- lib/lognorth/error_subscriber.rb
+- lib/lognorth/middleware.rb
+- lib/lognorth/railtie.rb
+homepage: https://lognorth.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://lognorth.com
+  source_code_uri: https://github.com/karloscodes/lognorth-sdk-rails
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: LogNorth SDK for Rails
+test_files: []