logister-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f3dcdd4ed71335923f5b4fd3d77dfa4af74a4d958715eaaf0805d704739f1a4
+  data.tar.gz: 147df51a94bea770c1559f0186eb74d154cd7a6b109a3b4025496ca8043abd68
+SHA512:
+  metadata.gz: d1328c3bb4188794e62215e0e2fd7e0c50631d0d1b3c92fbe3fec5dc179510109cfb95b43629f588f74ef8efe790d4c190db494d4ab4527b9229701cf9c7bddf
+  data.tar.gz: 8e700cdfbf1ff0b1f0178c260270170f448165f6043e04bca8f7c6ef5365254819ce223db9adcb40cdd12b7f1ce7d6f11212921f2dd2bc73edd2f70dba7af82e

data/README.md

@@ -0,0 +1,70 @@
+# logister-ruby
+
+`logister-ruby` sends application errors and custom metrics to `logister.org`.
+
+## Install
+
+```ruby
+gem "logister-ruby"
+```
+
+Then generate an initializer in Rails:
+
+```bash
+bin/rails generate logister:install
+```
+
+## Configuration
+
+```ruby
+Logister.configure do |config|
+  config.api_key = ENV.fetch("LOGISTER_API_KEY")
+  config.endpoint = "https://logister.org/api/v1/ingest_events"
+  config.environment = Rails.env
+  config.service = Rails.application.class.module_parent_name.underscore
+  config.release = ENV["RELEASE_SHA"]
+end
+```
+
+## Reliability options
+
+```ruby
+Logister.configure do |config|
+  config.async = true
+  config.queue_size = 1000
+  config.max_retries = 3
+  config.retry_base_interval = 0.5
+end
+```
+
+## Filtering and redaction
+
+```ruby
+Logister.configure do |config|
+  config.ignore_environments = ["development", "test"]
+  config.ignore_exceptions = ["ActiveRecord::RecordNotFound"]
+  config.ignore_paths = [/health/, "/up"]
+
+  config.before_notify = lambda do |payload|
+    payload[:context]&.delete("authorization")
+    payload
+  end
+end
+```
+
+## Rails auto-reporting
+
+If Rails is present, the gem installs middleware that reports unhandled exceptions automatically.
+
+## Manual reporting
+
+```ruby
+Logister.report_error(StandardError.new("Something failed"), tags: { area: "checkout" })
+
+Logister.report_metric(
+  message: "checkout.completed",
+  level: "info",
+  context: { duration_ms: 123 },
+  tags: { region: "us-east-1" }
+)
+```

data/lib/generators/logister/install_generator.rb

@@ -0,0 +1,13 @@
+require 'rails/generators'
+
+module Logister
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer
+        template 'logister.rb', 'config/initializers/logister.rb'
+      end
+    end
+  end
+end

data/lib/generators/logister/templates/logister.rb

@@ -0,0 +1,23 @@
+Logister.configure do |config|
+  config.api_key = ENV['LOGISTER_API_KEY']
+  config.endpoint = ENV.fetch('LOGISTER_ENDPOINT', 'https://logister.org/api/v1/ingest_events')
+  config.environment = Rails.env
+  config.service = Rails.application.class.module_parent_name.underscore
+  config.release = ENV['LOGISTER_RELEASE']
+
+  config.enabled = true
+  config.timeout_seconds = 2
+
+  config.async = true
+  config.queue_size = 1000
+  config.max_retries = 3
+  config.retry_base_interval = 0.5
+
+  config.ignore_environments = []
+  config.ignore_exceptions = []
+  config.ignore_paths = []
+
+  config.before_notify = lambda do |payload|
+    payload
+  end
+end

data/lib/logister/client.rb

@@ -0,0 +1,127 @@
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Logister
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+      @worker_mutex = Mutex.new
+      @queue = SizedQueue.new(@configuration.queue_size)
+      @worker = nil
+      @running = false
+    end
+
+    def publish(payload)
+      return false unless ready?
+
+      return publish_sync(payload) unless @configuration.async
+
+      ensure_worker_started
+      enqueue(payload)
+    end
+
+    def flush(timeout: 2)
+      return true unless @configuration.async
+
+      started_at = monotonic_now
+      while @queue.length.positive?
+        return false if monotonic_now - started_at > timeout
+
+        sleep(0.01)
+      end
+
+      true
+    end
+
+    def shutdown
+      return true unless @configuration.async
+
+      @running = false
+      begin
+        @queue.push(nil)
+      rescue StandardError
+        nil
+      end
+      @worker&.join(1)
+      true
+    end
+
+    private
+
+    def enqueue(payload)
+      @queue.push(payload, true)
+      true
+    rescue ThreadError
+      @configuration.logger.warn('logister queue full; dropping event')
+      false
+    end
+
+    def ensure_worker_started
+      return if @running && @worker&.alive?
+
+      @worker_mutex.synchronize do
+        return if @running && @worker&.alive?
+
+        @running = true
+        @worker = Thread.new { run_worker }
+      end
+    end
+
+    def run_worker
+      while @running
+        payload = @queue.pop
+        break if payload.nil?
+
+        publish_sync(payload)
+      end
+    rescue StandardError => e
+      @configuration.logger.warn("logister worker crashed: #{e.class} #{e.message}")
+      @running = false
+    end
+
+    def publish_sync(payload)
+      attempts = 0
+      begin
+        attempts += 1
+        send_request(payload)
+      rescue StandardError => e
+        if attempts <= @configuration.max_retries
+          sleep(@configuration.retry_base_interval * (2**(attempts - 1)))
+          retry
+        end
+
+        @configuration.logger.warn("logister publish failed: #{e.class} #{e.message}")
+        false
+      end
+    end
+
+    def send_request(payload)
+      uri = URI.parse(@configuration.endpoint)
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      request['Authorization'] = "Bearer #{@configuration.api_key}"
+      request.body = { event: payload }.to_json
+
+      response = Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == 'https',
+        open_timeout: @configuration.timeout_seconds,
+        read_timeout: @configuration.timeout_seconds
+      ) { |http| http.request(request) }
+
+      return true if response.is_a?(Net::HTTPSuccess)
+
+      raise "HTTP #{response.code}"
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def ready?
+      @configuration.enabled && @configuration.api_key.to_s != ''
+    end
+  end
+end

data/lib/logister/configuration.rb

@@ -0,0 +1,31 @@
+require 'logger'
+
+module Logister
+  class Configuration
+    attr_accessor :api_key, :endpoint, :environment, :service, :release, :enabled, :timeout_seconds, :logger,
+                  :ignore_exceptions, :ignore_environments, :ignore_paths, :before_notify,
+                  :async, :queue_size, :max_retries, :retry_base_interval
+
+    def initialize
+      @api_key = ENV['LOGISTER_API_KEY']
+      @endpoint = ENV.fetch('LOGISTER_ENDPOINT', 'https://logister.org/api/v1/ingest_events')
+      @environment = ENV.fetch('RAILS_ENV', ENV.fetch('RACK_ENV', 'development'))
+      @service = ENV.fetch('LOGISTER_SERVICE', 'ruby-app')
+      @release = ENV['LOGISTER_RELEASE']
+      @enabled = true
+      @timeout_seconds = 2
+      @logger = Logger.new($stdout)
+      @logger.level = Logger::WARN
+
+      @ignore_exceptions = []
+      @ignore_environments = []
+      @ignore_paths = []
+      @before_notify = nil
+
+      @async = true
+      @queue_size = 1000
+      @max_retries = 3
+      @retry_base_interval = 0.5
+    end
+  end
+end

data/lib/logister/middleware.rb

@@ -0,0 +1,21 @@
+module Logister
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @app.call(env)
+    rescue StandardError => e
+      Logister.report_error(
+        e,
+        context: {
+          request_id: env['action_dispatch.request_id'],
+          path: env['PATH_INFO'],
+          method: env['REQUEST_METHOD']
+        }
+      )
+      raise
+    end
+  end
+end

data/lib/logister/railtie.rb

@@ -0,0 +1,40 @@
+require 'rails/railtie'
+
+module Logister
+  class Railtie < Rails::Railtie
+    config.logister = ActiveSupport::OrderedOptions.new
+
+    initializer 'logister.configure' do |app|
+      Logister.configure do |config|
+        copy_setting(app, config, :api_key)
+        copy_setting(app, config, :endpoint)
+        copy_setting(app, config, :environment)
+        copy_setting(app, config, :service)
+        copy_setting(app, config, :release)
+        copy_setting(app, config, :enabled)
+        copy_setting(app, config, :timeout_seconds)
+        copy_setting(app, config, :ignore_exceptions)
+        copy_setting(app, config, :ignore_environments)
+        copy_setting(app, config, :ignore_paths)
+        copy_setting(app, config, :before_notify)
+        copy_setting(app, config, :async)
+        copy_setting(app, config, :queue_size)
+        copy_setting(app, config, :max_retries)
+        copy_setting(app, config, :retry_base_interval)
+      end
+    end
+
+    initializer 'logister.middleware' do |app|
+      app.middleware.use Logister::Middleware
+    end
+
+    private
+
+    def copy_setting(app, config, key)
+      value = app.config.logister.send(key)
+      return if value.nil?
+
+      config.send("#{key}=", value)
+    end
+  end
+end

data/lib/logister/reporter.rb

@@ -0,0 +1,124 @@
+require 'digest'
+require 'time'
+
+module Logister
+  class Reporter
+    def initialize(configuration)
+      @configuration = configuration
+      @client = Client.new(configuration)
+
+      at_exit { shutdown }
+    end
+
+    def report_error(exception, context: {}, tags: {}, level: 'error', fingerprint: nil)
+      return false if ignored_exception?(exception)
+      return false if ignored_path?(context)
+
+      payload = build_payload(
+        event_type: 'error',
+        level: level,
+        message: "#{exception.class}: #{exception.message}",
+        fingerprint: fingerprint || default_fingerprint(exception),
+        context: context.merge(
+          exception: {
+            class: exception.class.to_s,
+            message: exception.message.to_s,
+            backtrace: Array(exception.backtrace).first(50)
+          },
+          tags: tags
+        )
+      )
+
+      payload = apply_before_notify(payload)
+      return false unless payload
+
+      @client.publish(payload)
+    end
+
+    def report_metric(message:, level: 'info', context: {}, tags: {}, fingerprint: nil)
+      return false if ignored_environment?
+      return false if ignored_path?(context)
+
+      payload = build_payload(
+        event_type: 'metric',
+        level: level,
+        message: message,
+        fingerprint: fingerprint || Digest::SHA256.hexdigest(message.to_s)[0, 32],
+        context: context.merge(tags: tags)
+      )
+
+      payload = apply_before_notify(payload)
+      return false unless payload
+
+      @client.publish(payload)
+    end
+
+    def flush(timeout: 2)
+      @client.flush(timeout: timeout)
+    end
+
+    def shutdown
+      @client.shutdown
+    end
+
+    private
+
+    def build_payload(event_type:, level:, message:, fingerprint:, context:)
+      {
+        event_type: event_type,
+        level: level,
+        message: message,
+        fingerprint: fingerprint,
+        occurred_at: Time.now.utc.iso8601,
+        context: context.merge(
+          environment: @configuration.environment,
+          service: @configuration.service,
+          release: @configuration.release
+        )
+      }
+    end
+
+    def apply_before_notify(payload)
+      hook = @configuration.before_notify
+      return payload unless hook.respond_to?(:call)
+
+      result = hook.call(payload)
+      return nil if result == false || result.nil?
+
+      result
+    rescue StandardError => e
+      @configuration.logger.warn("logister before_notify failed: #{e.class} #{e.message}")
+      nil
+    end
+
+    def ignored_exception?(exception)
+      return true if ignored_environment?
+
+      @configuration.ignore_exceptions.any? do |item|
+        if item.is_a?(Class)
+          exception.is_a?(item)
+        else
+          exception.class.name == item.to_s
+        end
+      end
+    end
+
+    def ignored_environment?
+      env = @configuration.environment.to_s
+      @configuration.ignore_environments.map(&:to_s).include?(env)
+    end
+
+    def ignored_path?(context)
+      path = context[:path] || context['path']
+      return false if path.to_s.empty?
+
+      @configuration.ignore_paths.any? do |matcher|
+        matcher.is_a?(Regexp) ? matcher.match?(path.to_s) : path.to_s.include?(matcher.to_s)
+      end
+    end
+
+    def default_fingerprint(exception)
+      Digest::SHA256.hexdigest("#{exception.class}|#{exception.message}")[0, 32]
+    end
+  end
+end

data/lib/logister/version.rb

@@ -0,0 +1,3 @@
+module Logister
+  VERSION = '0.1.0'
+end

data/lib/logister.rb

@@ -0,0 +1,40 @@
+require_relative 'logister/version'
+require_relative 'logister/configuration'
+require_relative 'logister/client'
+require_relative 'logister/reporter'
+require_relative 'logister/middleware'
+
+module Logister
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      @reporter = nil
+    end
+
+    def reporter
+      @reporter ||= Reporter.new(configuration)
+    end
+
+    def report_error(exception, **kwargs)
+      reporter.report_error(exception, **kwargs)
+    end
+
+    def report_metric(**kwargs)
+      reporter.report_metric(**kwargs)
+    end
+
+    def flush(timeout: 2)
+      reporter.flush(timeout: timeout)
+    end
+
+    def shutdown
+      reporter.shutdown
+    end
+  end
+end
+
+require_relative 'logister/railtie' if defined?(Rails::Railtie)

data/logister-ruby.gemspec

@@ -0,0 +1,25 @@
+require_relative 'lib/logister/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'logister-ruby'
+  spec.version = Logister::VERSION
+  spec.authors = ['Logister']
+  spec.email = ['support@logister.org']
+
+  spec.summary = 'Send Rails errors and metrics to logister.org'
+  spec.description = 'Client gem for reporting errors and custom metrics from Ruby and Rails apps to logister.org'
+  spec.homepage = 'https://logister.org'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://logister.org'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('lib/**/*') + ['README.md', 'logister-ruby.gemspec']
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 6.1'
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: logister-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Logister
+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.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: Client gem for reporting errors and custom metrics from Ruby and Rails
+  apps to logister.org
+email:
+- support@logister.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/generators/logister/install_generator.rb
+- lib/generators/logister/templates/logister.rb
+- lib/logister.rb
+- lib/logister/client.rb
+- lib/logister/configuration.rb
+- lib/logister/middleware.rb
+- lib/logister/railtie.rb
+- lib/logister/reporter.rb
+- lib/logister/version.rb
+- logister-ruby.gemspec
+homepage: https://logister.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://logister.org
+  source_code_uri: https://logister.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Send Rails errors and metrics to logister.org
+test_files: []