tracetells 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5537eb8ff5c01294ae19f4cfbecc455d69b6908e28afc72a5598d690a04d3753
+  data.tar.gz: 7d8e577665f1846717d2ce5c214425735479208178ebc5afa54cd86c8bd3b474
+SHA512:
+  metadata.gz: 78067850640ffa59dc4c9149107d5a8b80f069d33e301d9a50c562c9478068f4b3eda695c95289124659958218d2e364b2aa236dfc5be8a544ee68d3109fdb8a
+  data.tar.gz: 4e0b84ef279742c39dd0f7db79247f9ca28cdfe4ad47ae7e66489ddd06ad4d8cc41c6f00868023ac1b87f94150e06a25e222c01c6baf29325557184c3176ff46

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deyan Dobrinov
+
+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,49 @@
+# tracetells
+
+Report a Ruby server's errors to [Trace](https://tracetells.com): what failed, where in your code, on which route, since which release. Trace groups and counts them, shows how many visits each one broke in the browser, and tells you whether a fix stopped it. No runtime dependencies; Ruby 3.1+.
+
+```ruby
+# Gemfile
+gem "tracetells"
+```
+
+**Rails:** nothing else. The gem configures itself from the environment, adds its Rack middleware, and subscribes to `Rails.error`, which sees unhandled errors in controllers and jobs (Rails 7+). Routes come from Rails (7.1+): `/orders/:id`, never the URL. Errors Rails answers with a 4xx (`RecordNotFound`, `RoutingError`) aren't reported.
+
+**Rack and Sinatra:**
+
+```ruby
+# config.ru
+require "tracetells"
+Tracetells.configure
+use Tracetells::Rack # reports exceptions with their route and re-raises them
+```
+
+Report an error you handled with `Tracetells.report(error)`, or `Tracetells.report_message("Billing", "no plan for account")`. During a request, its route goes with it.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `TRACE_SERVER_KEY` | – | The website's server key. Your coding agent creates it (`/trace:setup server errors`), or an admin in the dashboard. Keep it in your credentials, never in the repository. Without it the gem does nothing. |
+| `TRACE_ENDPOINT` | `https://app.tracetells.com` | Your own server, when you self-host Trace |
+| `TRACE_ENVIRONMENT` | `RAILS_ENV`, `RACK_ENV`, else `production` | |
+| `TRACE_RELEASE` | `SOURCE_VERSION`, `HEROKU_SLUG_COMMIT`, `RENDER_GIT_COMMIT`, `GIT_COMMIT` or `GITHUB_SHA`, if set | The release the code belongs to |
+
+Or in code: `Tracetells.configure(key:, endpoint:, environment:, release:)`.
+
+## What it sends, and what it never does
+
+**Sent:** the error's class, its message (with up to three causes), the backtrace (files relative to your project, lines, methods, and whether each frame is your code), the route template, the HTTP method and status, the environment, the release, the Ruby version, when it happened and how often.
+
+**Never sent:** request or response bodies, params, query strings, headers, cookies, sessions, environment variables, source code, host names or who was signed in. There is no option to send them.
+
+Messages and file paths are scrubbed before they leave: emails, tokens, card numbers, IBANs and phone-like numbers are replaced, and home directories are cut from paths. Trace's server scrubs everything again. Keep personal data out of exception messages anyway.
+
+## How it behaves
+
+- Errors are sent from a background thread, in batches, at most once a second. Requests never wait for it. After a fork (Puma, Unicorn) a new thread starts by itself.
+- The first occurrence of an error is sent right away; repeats within the next minute are sent once, as a count.
+- A full queue, a network error, or Trace answering 429 or 5xx: errors are dropped, and the client backs off (5 seconds, doubling up to 5 minutes). It never raises into your code.
+- At exit it sends what's queued, waiting at most two seconds.
+
+Licence: MIT.

data/lib/tracetells/client.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Tracetells
+  # Collects errors and sends them from a background thread: in batches, at
+  # most once a second, with repeats within a minute folded into a count, and
+  # backing off when Trace is unreachable or asks to slow down.
+  class Client
+    QUEUE = 1000
+    BATCH = 100
+    FOLD = 60
+    SEND_EVERY = 1.0
+
+    attr_reader :environment, :release
+
+    def initialize(key:, endpoint:, environment:, release:)
+      @key = key
+      @uri = URI("#{endpoint}/v1/errors")
+      @environment = environment.to_s
+      @release = release.to_s
+      @queue = Thread::Queue.new
+      @recent = {}
+      @outgoing = []
+      @paused_until = 0
+      @backoff = 5
+      @lock = Mutex.new
+      @pid = Process.pid
+    end
+
+    def report(error, request)
+      enqueue(event(error.class.name || "Error", Scrub.message(chain(error)), error.backtrace || caller(2), request))
+    end
+
+    def report_message(class_name, message, request)
+      enqueue(event(class_name.to_s, Scrub.message(message), caller(2), request))
+    end
+
+    def flush(timeout)
+      done = Thread::Queue.new
+      start
+      @queue << [:flush, done]
+      done.pop(timeout: timeout)
+    end
+
+    def shutdown
+      @queue << [:stop, nil]
+    end
+
+    private
+
+    def chain(error)
+      msg = error.message.to_s
+      cause = error.cause
+      3.times do
+        break unless cause
+
+        msg += ": #{cause.message}"
+        cause = cause.cause
+      end
+      msg
+    end
+
+    def event(class_name, message, backtrace, request)
+      request ||= {}
+      status = request[:status].to_i
+      {
+        "class" => Scrub.truncate(Scrub.one_line(class_name), 200),
+        "message" => Scrub.truncate(message, 300),
+        "backtrace" => frames(backtrace),
+        "route" => request[:route].to_s.empty? ? "" : Scrub.route(request[:route]),
+        "method" => request[:method].to_s.upcase,
+        "status" => status.between?(100, 599) ? status : nil,
+        "occurred_at" => (Time.now.to_f * 1000).to_i,
+        "count" => 1
+      }
+    end
+
+    RUBY_LIB = RbConfig::CONFIG["rubylibdir"].to_s
+
+    # "/srv/app/app/models/order.rb:12:in 'Order#total'" (Ruby 3.4+ quotes, older ones backtick-quote).
+    def frames(lines)
+      Array(lines).first(60).filter_map do |line|
+        m = /\A(.+?):(\d+)(?::in [`'](.+)')?\z/.match(line.to_s)
+        next unless m
+
+        file = m[1]
+        next if file.include?("/lib/tracetells")
+
+        dependency = file.include?("/gems/") || file.start_with?("<internal:") || (!RUBY_LIB.empty? && file.start_with?(RUBY_LIB))
+        { "file" => Scrub.file(file), "line" => m[2].to_i, "function" => Scrub.truncate(Scrub.one_line(m[3].to_s), 200), "in_app" => !dependency }
+      end.first(40)
+    end
+
+    def enqueue(e)
+      start
+      @queue << [:event, e] if @queue.size < QUEUE
+    end
+
+    # After a fork (Puma, Unicorn) the thread is gone: start a new one.
+    def start
+      @lock.synchronize do
+        if @pid != Process.pid
+          @pid = Process.pid
+          @thread = nil
+        end
+        @thread = Thread.new { run } unless @thread&.alive?
+      end
+    end
+
+    def run
+      Thread.current.name = "tracetells"
+      Thread.current.report_on_exception = false
+      last_send = monotonic
+      loop do
+        kind, payload = @queue.pop(timeout: SEND_EVERY)
+        flushing = nil
+        case kind
+        when :event then admit(payload)
+        when :flush then flushing = payload
+        when :stop then return
+        end
+        fold_expired(!flushing.nil?)
+        if !@outgoing.empty? && (flushing || @outgoing.size >= BATCH || monotonic - last_send >= SEND_EVERY)
+          send_all
+          last_send = monotonic
+        end
+        flushing&.push(true)
+      end
+    rescue StandardError
+      nil
+    end
+
+    def admit(e)
+      key = fold_key(e)
+      seen = @recent[key]
+      if seen && monotonic - seen[:start] < FOLD
+        seen[:repeats] += 1
+        seen[:latest] = e
+      else
+        @recent[key] = { start: monotonic, repeats: 0, latest: nil }
+        @outgoing << e
+      end
+    end
+
+    def fold_key(e)
+      top = e["backtrace"].find { |f| f["in_app"] }
+      [e["class"], top ? "#{top['file']}|#{top['function']}" : e["message"], e["route"], e["status"]].join("|")
+    end
+
+    # Minutes that ended: their repeats go out as one error with a count.
+    def fold_expired(all)
+      now = monotonic
+      @recent.delete_if do |_, r|
+        ended = now - r[:start] >= FOLD
+        if (ended || all) && r[:latest] && r[:repeats].positive?
+          @outgoing << r[:latest].merge("count" => r[:repeats])
+          r[:repeats] = 0
+          r[:latest] = nil
+        end
+        ended
+      end
+    end
+
+    def send_all
+      until @outgoing.empty?
+        batch = @outgoing.shift(BATCH)
+        next if monotonic < @paused_until # backing off: drop rather than pile up
+
+        runtime = { "name" => RUBY_ENGINE, "version" => RUBY_VERSION }
+        body = JSON.generate("errors" => batch.map { |e| e.merge("environment" => @environment, "release" => @release, "runtime" => runtime) })
+        begin
+          res = Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == "https", open_timeout: 5, read_timeout: 5, write_timeout: 5) do |http|
+            http.post(@uri.path, body, "authorization" => "Bearer #{@key}", "content-type" => "application/json")
+          end
+          code = res.code.to_i
+          raise "HTTP #{code}" if code == 429 || code >= 500
+
+          @backoff = 5
+        rescue StandardError
+          @paused_until = monotonic + @backoff
+          @backoff = [@backoff * 2, 300].min
+        end
+      end
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/tracetells/rack.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tracetells
+  # Rack middleware: reports exceptions raised while handling a request, with
+  # its route, method and status, and re-raises them so the app's own error
+  # handling is unchanged. In Rails the Railtie adds it.
+  class Rack
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      previous = Thread.current[:tracetells_env]
+      Thread.current[:tracetells_env] = env
+      @app.call(env)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      Tracetells.report(e, request: self.class.request_info(env, status: 500)) unless env["tracetells.reported"]
+      raise
+    ensure
+      Thread.current[:tracetells_env] = previous
+    end
+
+    # The route template when the framework knows it (Rails 7.1+, Sinatra), else
+    # the path, which is scrubbed of ids before it's sent. Nothing else of the request.
+    def self.request_info(env, status: nil)
+      route = env["action_dispatch.route_uri_pattern"] || env["sinatra.route"]&.split(" ", 2)&.last || env["PATH_INFO"].to_s
+      { route: route.to_s.sub(/\(\.:format\)\z/, ""), method: env["REQUEST_METHOD"], status: status }
+    end
+  end
+end

data/lib/tracetells/railtie.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Tracetells
+  # In Rails: configures from the environment, adds the Rack middleware, and
+  # subscribes to Rails.error, which sees unhandled errors in controllers and
+  # jobs (Rails 7+). Handled errors reported with `handled: true` are left out
+  # unless their severity is :error, and so are errors Rails answers with a 4xx.
+  class Railtie < ::Rails::Railtie
+    initializer "tracetells.middleware" do |app|
+      Tracetells.configure unless Tracetells.client
+      app.middleware.insert_before(0, Tracetells::Rack)
+    end
+
+    config.after_initialize do
+      Rails.error.subscribe(Tracetells::Railtie::Subscriber.new) if Rails.respond_to?(:error)
+    end
+
+    class Subscriber
+      def report(error, handled:, severity:, context:, source: nil)
+        return if handled && severity != :error
+
+        env = Thread.current[:tracetells_env]
+        status = status_for(error)
+        # 404s and other client errors (RecordNotFound, RoutingError) aren't server errors.
+        return if env && status < 500
+
+        request = env ? Tracetells::Rack.request_info(env, status: status) : nil
+        env["tracetells.reported"] = true if env
+        Tracetells.report(error, request: request)
+      end
+
+      private
+
+      def status_for(error)
+        if defined?(ActionDispatch::ExceptionWrapper)
+          ActionDispatch::ExceptionWrapper.status_code_for_exception(error.class.name)
+        else
+          500
+        end
+      end
+    end
+  end
+end

data/lib/tracetells/scrub.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Tracetells
+  # The same scrubbing Trace's server does (crates/trace-core/src/privacy.rs
+  # and errors.rs), done here first so nothing personal leaves the server.
+  # clients/test-vectors.json holds the cases every client must agree on.
+  module Scrub
+    EMAIL = /[a-z0-9._%+-]+(@|%40)[a-z0-9.-]+\.[a-z]{2,}/i
+    JWT = /\beyJ[\w-]+\.[\w-]+\.[\w-]+/
+    URL_QUERY = %r{(https?://[^\s?#]+)[?#][^\s]*}
+    IBAN = /\b[A-Z]{2}\d{2}(?:\s?[A-Z0-9]{4}){2,7}(?:\s?[A-Z0-9]{1,4})?\b/
+    CARD = /\b(?:\d[ -]?){12,18}\d\b/
+    TOKEN = %r{[A-Za-z0-9_\-+/=]{20,}}
+    LONG_NUMBER = /\+?\d(?:[\s().-]{0,2}\d){6,}/
+    HIDDEN = /[\u0000-\u001f\u007f-\u009f\u00ad\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]/
+
+    DEPENDENCY_ROOTS = ["node_modules/", "gems/", "registry/src/", "site-packages/", "vendor/"].freeze
+    PROJECT_ROOTS = ["src/", "app/", "lib/", "crates/", "packages/", "config/", "bin/", "spec/", "test/", "tests/"].freeze
+
+    module_function
+
+    def token?(s)
+      s.match?(/\d/) && s.match?(/[A-Za-z]/)
+    end
+
+    # On one line: control and invisible characters become spaces, backticks quotes.
+    def one_line(s)
+      s.to_s.scrub("?").gsub(HIDDEN, " ").tr("`", "'").squeeze(" ").strip
+    end
+
+    def truncate(s, max)
+      s.length > max ? s[0, max] : s
+    end
+
+    # Emails, tokens, card numbers, IBANs, phone-like numbers and URL query strings.
+    def message(s)
+      one_line(s)
+        .gsub(URL_QUERY, '\1?[redacted]')
+        .gsub(EMAIL, "[email]")
+        .gsub(JWT, "[token]")
+        .gsub(IBAN, "[iban]")
+        .gsub(CARD, "[card]")
+        .gsub(TOKEN) { |m| token?(m) ? "[token]" : m }
+        .gsub(LONG_NUMBER, "[number]")
+    end
+
+    # A route as Trace stores it: no query string, segments that look like ids,
+    # emails or tokens replaced. Route parameters (:id, {id}) pass through.
+    def route(path)
+      p = one_line(path.to_s.strip).gsub(" ", "%20").split(/[?#]/).first.to_s
+      return "" unless p.start_with?("/")
+
+      out = p.split("/", -1).map do |seg|
+        if seg.length > 2 && seg.start_with?("{") && seg.end_with?("}")
+          ":#{seg[1..-2].delete_prefix('*')}"
+        elsif seg.empty? || seg.start_with?(":") || seg == "*"
+          seg
+        elsif seg.include?("@") || seg.downcase.include?("%40")
+          ":email"
+        elsif seg.include?("=") || (seg.count(".") >= 2 && seg.length >= 24)
+          ":token"
+        elsif seg.count("0-9") >= 3 || (seg.length >= 16 && token?(seg)) || (seg.length >= 16 && seg.match?(/\A\h+\z/))
+          ":id"
+        else
+          seg
+        end
+      end.join("/")
+      truncate(out, 200)
+    end
+
+    # A frame's file, relative to the project or the dependency it is in.
+    def file(name)
+      f = one_line(name).tr("\\", "/")
+      f = f.delete_prefix("file://")
+      f = f.split(/[?#]/).first.to_s
+      absolute = f.start_with?("/") || f[1] == ":" || f.start_with?("~/")
+      rel =
+        if !absolute
+          f
+        elsif (dep = DEPENDENCY_ROOTS.filter_map { |m| (i = f.rindex(m)) && [i, m] }.max_by(&:first))
+          i, m = dep
+          if m == "registry/src/"
+            rest = f[(i + m.length)..]
+            (slash = rest.index("/")) ? rest[(slash + 1)..] : rest
+          else
+            f[i..]
+          end
+        elsif (i = PROJECT_ROOTS.lazy.map { |m| f.index("/#{m}") }.find(&:itself))
+          f[(i + 1)..]
+        else
+          f.split("/").last.to_s
+        end
+      truncate(rel.split("/", -1).map { |seg| seg.include?("@") ? ":email" : seg }.join("/"), 200)
+    end
+  end
+end

data/lib/tracetells/version.rb

@@ -0,0 +1,3 @@
+module Tracetells
+  VERSION = "0.1.0"
+end

data/lib/tracetells.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Report a Ruby server's errors to Trace (https://tracetells.com).
+#
+#   Tracetells.configure # TRACE_SERVER_KEY, TRACE_ENDPOINT, TRACE_ENVIRONMENT, TRACE_RELEASE
+#   use Tracetells::Rack # in config.ru; Rails apps get it, and Rails.error, on their own
+#
+# What is sent: the error's class, its message, the backtrace (files relative
+# to your project, lines, methods), the route template, the HTTP method and
+# status, the environment, the release, the Ruby version, when and how often.
+# Never sent: request or response bodies, params, query strings, headers,
+# cookies, sessions, environment variables, source code, host names or who was
+# signed in. There is no option to send them. Messages and paths are scrubbed first.
+
+require "json"
+require "net/http"
+require "uri"
+require "rbconfig"
+require_relative "tracetells/version"
+require_relative "tracetells/scrub"
+require_relative "tracetells/client"
+require_relative "tracetells/rack"
+require_relative "tracetells/railtie" if defined?(::Rails::Railtie)
+
+module Tracetells
+  class << self
+    # Starts the client. Without a key it does nothing. Options override the environment.
+    def configure(key: nil, endpoint: nil, environment: nil, release: nil)
+      env = ->(k) { (v = ENV[k].to_s.strip).empty? ? nil : v }
+      key ||= env.("TRACE_SERVER_KEY")
+      return @client = nil unless key
+
+      @client&.shutdown
+      @client = Client.new(
+        key: key,
+        endpoint: (endpoint || env.("TRACE_ENDPOINT") || "https://app.tracetells.com").sub(%r{/+\z}, ""),
+        environment: environment || env.("TRACE_ENVIRONMENT") || env.("RAILS_ENV") || env.("RACK_ENV") || "production",
+        release: release || %w[TRACE_RELEASE SOURCE_VERSION HEROKU_SLUG_COMMIT RENDER_GIT_COMMIT GIT_COMMIT GITHUB_SHA].lazy.map { |k| env.(k) }.find(&:itself) || ""
+      )
+    end
+
+    def client
+      @client
+    end
+
+    # Reports an error you handled. `request` takes :route, :method and :status.
+    def report(error, request: nil)
+      @client&.report(error, request || current_request)
+    rescue StandardError
+      nil
+    end
+
+    def report_message(class_name, message, request: nil)
+      @client&.report_message(class_name, message, request || current_request)
+    rescue StandardError
+      nil
+    end
+
+    # Sends what's queued, waiting at most `timeout` seconds.
+    def flush(timeout = 2)
+      @client&.flush(timeout)
+    end
+
+    # The request this thread is handling, as Tracetells::Rack saw it.
+    def current_request
+      env = Thread.current[:tracetells_env]
+      env && Tracetells::Rack.request_info(env)
+    end
+  end
+end
+
+at_exit { Tracetells.flush(2) }

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: tracetells
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Deyan Dobrinov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Sends the class, message, backtrace, route, status and release of your
+  app's errors to Trace, which groups and counts them and ties them to the visits
+  they broke. Never request bodies, params, headers, cookies or users.
+email: hello@tracetells.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/tracetells.rb
+- lib/tracetells/client.rb
+- lib/tracetells/rack.rb
+- lib/tracetells/railtie.rb
+- lib/tracetells/scrub.rb
+- lib/tracetells/version.rb
+homepage: https://tracetells.com/docs/server-errors/
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/dobrinov/tracetells/tree/main/clients/ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: 'Report Ruby server errors to Trace (tracetells.com): error facts only, scrubbed,
+  in the background'
+test_files: []