activeusage 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a3a473fcb948b9b5cde6090665a070a1900e5627bb624b51119b1c19cd8461d
+  data.tar.gz: ab79d115a01c4e395fb9547a71813dbbefed37fc5d31301c7e15fd94048faa52
+SHA512:
+  metadata.gz: 7f413eb559b86bdf5091c2b751ea1659f582137703d371b8db45dd21f57a13782de2f8308c2172305d7dc746903accc96896631a15b156af30ae8c3d40677490
+  data.tar.gz: 614c765005e2543cf3bf68aee7af650fca2c5b9b1596dcdb5276faebf079a7015faae55e0ec5528a8b44d63943b0cbf1b34406b63a7ba7dcb6493f5864c2ef01

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-21
+
+### Added
+
+- Rails auto-instrumentation for requests (`process_action.action_controller`) and jobs (`ActiveJob`)
+- Manual task tracking via `ActiveUsage.track`
+- Thread-local tag management with per-request and per-job flush
+- SQL query fingerprinting with normalization, aggregation by pattern, and top-N ranking (up to 20 per event)
+- HTTP adapter with Bearer token auth and JSON batch delivery
+- Custom adapter interface (`ActiveUsage::Adapters::Base`)
+- Background worker with configurable flush interval and graceful shutdown
+- Thread-safe event queue with batch flushing and dropped-event tracking
+- Configurable logger, window size, global tags, and adapter via `ActiveUsage.configure`
+- Railtie for zero-config Rails integration (middleware + ActiveJob hook)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Tomasz Kowalewski
+
+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,69 @@
+# ActiveUsage
+
+Cost observability core for Ruby and Rails workloads. ActiveUsage turns runtime signals — request timing, SQL queries, job execution — into structured events you can ship to any backend for cost analysis.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "activeusage"
+```
+
+## Configuration
+
+```ruby
+ActiveUsage.configure do |config|
+  config.adapter     = ActiveUsage::Adapters::Http.new("https://your-backend.example.com/events", "your-api-key")
+  config.tags        = { env: Rails.env }
+  config.logger      = Rails.logger
+end
+```
+
+## Rails integration
+
+With Rails, ActiveUsage auto-instruments requests and jobs via a Railtie — no extra setup needed.
+
+**Requests** — every `process_action.action_controller` notification produces a `:request` event with timing, allocations, controller/action tags, and SQL query breakdown.
+
+**Jobs** — every `ActiveJob` execution produces a `:job` event with timing, retry count, queue name, and SQL query breakdown.
+
+**Middleware** — `ActiveUsage::Middleware` is inserted automatically to flush per-request tags.
+
+## Manual tracking
+
+Use `ActiveUsage.track` to instrument arbitrary blocks:
+
+```ruby
+result = ActiveUsage.track("reports.generate", tags: { user_id: current_user.id }) do
+  ReportGenerator.call(params)
+end
+```
+
+This produces a `:task` event with timing and SQL queries captured within the block.
+
+## Tags
+
+Tags are thread-local and merged into every event recorded on the current thread:
+
+```ruby
+ActiveUsage.tags.tag(user_id: current_user.id, tenant: current_tenant.slug)
+```
+
+Tags set on the thread are flushed automatically at the end of each request by the middleware and at the start/end of each job by the hook.
+
+## Event payload
+
+Every event includes:
+
+| Field | Description |
+|---|---|
+| `type` | `:request`, `:job`, or `:task` |
+| `name` | controller action, job class name, or task name |
+| `started_at` | start timestamp |
+| `finished_at` | end timestamp |
+| `allocations` | object allocations (requests only) |
+| `retry_count` | retry count (jobs only) |
+| `tags` | merged thread-local and per-event tags |
+| `window_started_at` | start of the aggregation window bucket |
+| `sql_queries` | top SQL query fingerprints with timing and call counts |

data/lib/active_usage/adapters/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  module Adapters
+    class Base
+      def record(_events)
+        raise NotImplementedError
+      end
+
+      def clear!
+        raise NotImplementedError
+      end
+
+      def shutdown!
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/active_usage/adapters/http.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  module Adapters
+    class Http < Base
+      class Client
+        def initialize(url, api_key, events)
+          @uri = URI(url)
+          @api_key = api_key
+          @events = events
+        end
+
+        def call
+          Net::HTTP.start(@uri.host, @uri.port, options) do |http|
+            http.request(request).is_a?(Net::HTTPSuccess)
+          end
+        rescue StandardError
+          false
+        end
+
+        private
+
+        def request
+          request = Net::HTTP::Post.new(@uri)
+          request["Content-Type"] = "application/json"
+          request["Authorization"] = "Bearer #{@api_key}"
+          request.body = JSON.generate(
+            events: @events.map(&:attributes)
+          )
+          request
+        end
+
+        def options
+          {
+            use_ssl: @uri.scheme == "https",
+            read_timeout: 2.0,
+            open_timeout: 2.0
+          }
+        end
+      end
+
+      def initialize(url, api_key)
+        @url = url
+        @api_key = api_key
+      end
+
+      def record(events)
+        return true if events.empty?
+
+        Client.new(@url, @api_key, events).call
+      end
+
+      def clear!; end
+
+      def shutdown!; end
+    end
+  end
+end

data/lib/active_usage/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  # Holds configuration options for the ActiveUsage gem.
+  class Configuration
+    attr_accessor :adapter, :tags, :window_size
+    attr_writer :logger
+
+    def initialize
+      @tags = {}
+      @window_size = 300
+    end
+
+    def logger
+      @logger || (defined?(Rails.logger) && Rails.logger) || Logger.new($stderr)
+    end
+  end
+end

data/lib/active_usage/event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  # Represents a single tracked usage event with timing, resource.
+  class Event
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :type, :string
+    attribute :name, :string
+    attribute :started_at, :datetime
+    attribute :finished_at, :datetime
+    attribute :allocations, :integer
+    attribute :retry_count, :integer
+    attribute :tags, :tags
+    attribute :window_started_at, :datetime
+    attribute :sql_queries, :sql_queries
+  end
+end

data/lib/active_usage/event_queue.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class EventQueue
+    def initialize(max_size, batch_size)
+      @max_size = max_size
+      @batch_size = batch_size
+      @queue = Queue.new
+      @mutex = Mutex.new
+      @dropped_count = 0
+    end
+
+    def push(event)
+      @mutex.synchronize do
+        if @queue.size >= @max_size
+          @dropped_count += 1
+          return
+        end
+        @queue << event
+      end
+    end
+
+    def drain
+      items = []
+      @mutex.synchronize do
+        items << @queue.pop(true) while items.size < @batch_size && !@queue.empty?
+      rescue ThreadError
+        nil
+      end
+      items
+    end
+
+    def size
+      @mutex.synchronize { @queue.size }
+    end
+
+    def flush_ready?
+      size >= @batch_size
+    end
+
+    def dropped_count
+      @mutex.synchronize { @dropped_count }
+    end
+  end
+end

data/lib/active_usage/instrumentation/active_job_hook.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  module Instrumentation
+    module ActiveJobHooks
+      extend ActiveSupport::Concern
+
+      included do
+        around_perform do |job, block|
+          ActiveUsage.tags.flush
+          ActiveUsage::Instrumentation::RuntimeState.clear_sql_state
+          started_at = Time.current
+
+          block.call
+        ensure
+          ActiveUsage.record(
+            type: :job,
+            name: job.class.name,
+            started_at: started_at,
+            finished_at: Time.current,
+            retry_count: job.respond_to?(:executions) ? job.executions.to_i - 1 : 0,
+            tags: { queue: job.queue_name },
+            sql_queries: ActiveUsage::Instrumentation::RuntimeState.consume_sql_queries
+          )
+          ActiveUsage.store.flush!
+          ActiveUsage::Instrumentation::RuntimeState.clear_sql_state
+          ActiveUsage.tags.flush
+        end
+      end
+    end
+  end
+end

data/lib/active_usage/instrumentation/runtime_state.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  module Instrumentation
+    module RuntimeState
+      SQL_FINGERPRINTS_KEY = :activeusage_sql_fingerprints
+      MAX_SQL_QUERIES_PER_EVENT = 20
+
+      module_function
+
+      def sql_fingerprints
+        ActiveSupport::IsolatedExecutionState[SQL_FINGERPRINTS_KEY] || {}
+      end
+
+      def add_sql_event(payload, started_at:, finished_at:)
+        duration_ms = ((finished_at - started_at) * 1000.0).round(3)
+        ActiveSupport::IsolatedExecutionState[SQL_FINGERPRINTS_KEY] = accumulate_sql_fingerprint(
+          sql_fingerprints,
+          payload: payload,
+          duration_ms: duration_ms
+        )
+      end
+
+      def clear_sql_state
+        ActiveSupport::IsolatedExecutionState[SQL_FINGERPRINTS_KEY] = {}
+      end
+
+      def consume_sql_queries
+        queries = sql_fingerprints
+        ActiveSupport::IsolatedExecutionState[SQL_FINGERPRINTS_KEY] = {}
+        queries.values
+               .sort_by { |query| -query[:total_duration_ms].to_f }
+               .first(MAX_SQL_QUERIES_PER_EVENT)
+               .map { |query| format_sql_query(query) }
+      end
+
+      def accumulate_sql_fingerprint(fingerprints, payload:, duration_ms:)
+        fingerprint = normalize_sql(payload[:sql].to_s)
+        return fingerprints if fingerprint.empty?
+
+        entry = find_or_build_entry(fingerprints, fingerprint, payload)
+        update_entry(entry, duration_ms, payload)
+        fingerprints.merge(fingerprint => entry)
+      end
+
+      def normalize_sql(sql)
+        normalized = sql.dup
+        normalized.gsub!(/'(?:[^']|'')*'/, "?")
+        normalized.gsub!(/"([^"]*)"/, '\1')
+        normalized.gsub!(/\$\d+/, "?")
+        normalized.gsub!(/\b\d+(?:\.\d+)?\b/, "?")
+        normalized.gsub!(/\(\s*\?(?:\s*,\s*\?)+\s*\)/, "(?)")
+        normalized.gsub!(/\s+/, " ")
+        normalized.strip!
+        normalized
+      end
+
+      def format_sql_query(query)
+        {
+          fingerprint: query[:fingerprint],
+          total_duration_ms: query[:total_duration_ms].to_f.round(3),
+          calls: query[:calls].to_i,
+          adapter_name: query[:adapter_name]
+        }
+      end
+
+      def find_or_build_entry(fingerprints, fingerprint, payload)
+        fingerprints[fingerprint] || {
+          fingerprint: fingerprint,
+          total_duration_ms: 0.0,
+          calls: 0,
+          adapter_name: payload[:name].to_s
+        }
+      end
+
+      def update_entry(entry, duration_ms, payload)
+        entry[:total_duration_ms] += duration_ms.to_f
+        entry[:calls] += 1
+        entry[:adapter_name] = payload[:name].to_s if entry[:adapter_name].to_s.empty?
+      end
+
+      private_class_method :format_sql_query, :find_or_build_entry, :update_entry
+    end
+  end
+end

data/lib/active_usage/instrumentation/subscriber.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  module Instrumentation
+    class Subscriber
+      ACTION_CONTROLLER_EVENT = "process_action.action_controller"
+
+      @subscriptions = []
+
+      class << self
+        def unsubscribe_all
+          @subscriptions.each { |s| ActiveSupport::Notifications.unsubscribe(s) }
+          @subscriptions = []
+        end
+
+        def track(subscriptions)
+          @subscriptions = subscriptions
+        end
+      end
+
+      def call
+        self.class.unsubscribe_all
+        self.class.track([subscribe_to_sql, subscribe_to_actions])
+      end
+
+      private
+
+      def subscribe_to_sql
+        ActiveSupport::Notifications.subscribe("sql.active_record") do |_name, started, finished, _id, payload|
+          next if payload[:cached]
+
+          ActiveUsage::Instrumentation::RuntimeState.add_sql_event(
+            payload,
+            started_at: started,
+            finished_at: finished
+          )
+        end
+      end
+
+      def subscribe_to_actions
+        ActiveSupport::Notifications.subscribe(ACTION_CONTROLLER_EVENT) do |_name, started, finished, _id, payload|
+          handle_action(started, finished, payload)
+        end
+      end
+
+      def handle_action(started, finished, payload)
+        ActiveUsage.record(**action_event_attributes(started, finished, payload))
+      end
+
+      def action_event_attributes(started, finished, payload)
+        {
+          type: :request,
+          name: controller_action_name(payload),
+          started_at: started,
+          finished_at: finished,
+          allocations: payload[:allocations].to_i,
+          tags: { controller: payload[:controller], action: payload[:action] }
+        }.merge(sql_event_attributes)
+      end
+
+      def sql_event_attributes
+        {
+          sql_queries: ActiveUsage::Instrumentation::RuntimeState.consume_sql_queries
+        }
+      end
+
+      def controller_action_name(payload)
+        [payload[:controller], payload[:action]].compact.join("#")
+      end
+    end
+  end
+end

data/lib/active_usage/middleware.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      ActiveUsage.tags.flush
+      @app.call(env)
+    ensure
+      ActiveUsage.tags.flush
+    end
+  end
+end

data/lib/active_usage/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class Railtie < Rails::Railtie
+    initializer "activeusage.middleware" do |app|
+      app.middleware.use ActiveUsage::Middleware
+    end
+
+    initializer "activeusage.active_job_hooks" do
+      ActiveSupport.on_load(:active_job) do
+        include ActiveUsage::Instrumentation::ActiveJobHooks
+      end
+    end
+
+    config.after_initialize do
+      ActiveUsage::Instrumentation::Subscriber.new.call
+    end
+  end
+end

data/lib/active_usage/recorder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class Recorder
+    def initialize(attributes)
+      @attributes = attributes
+    end
+
+    def call(store)
+      store.record(event)
+      ActiveSupport::Notifications.instrument("activeusage.event_recorded", event: event)
+
+      event
+    end
+
+    private
+
+    def event
+      @event ||= Event.new(@attributes)
+    end
+  end
+end

data/lib/active_usage/store.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class Store
+    @instances_mutex = Mutex.new
+    @instances = []
+    @exit_hook_installed = false
+
+    class << self
+      def track(instance)
+        @instances_mutex.synchronize do
+          unless @exit_hook_installed
+            at_exit do
+              live = @instances_mutex.synchronize { @instances.dup }
+              live.each(&:shutdown!)
+            end
+            @exit_hook_installed = true
+          end
+          @instances << instance
+        end
+      end
+
+      def untrack(instance)
+        @instances_mutex.synchronize { @instances.delete(instance) }
+      end
+    end
+
+    def initialize(adapter, batch_size: 100, flush_interval: 1.0, max_queue_size: 10_000)
+      @adapter = adapter
+      @queue = EventQueue.new(max_queue_size, batch_size)
+      @flush_mutex = Mutex.new
+      @shutdown_mutex = Mutex.new
+      @shutdown = false
+      @worker = Worker.new(flush_interval) { flush! }
+      self.class.track(self)
+    end
+
+    def record(event)
+      @queue.push(event)
+      flush! if @queue.flush_ready?
+      event
+    end
+
+    def clear!
+      flush!
+      @adapter.clear!
+    end
+
+    def flush!
+      @flush_mutex.synchronize do
+        batch = @queue.drain
+        return if batch.empty?
+
+        begin
+          @adapter.record(batch)
+        rescue StandardError
+          batch.each { |event| @queue.push(event) }
+          raise
+        end
+      end
+    end
+
+    def shutdown!
+      @shutdown_mutex.synchronize do
+        return if @shutdown
+
+        @shutdown = true
+      end
+
+      @worker.stop!
+      @worker.join(0.5)
+      flush!
+      @adapter.shutdown!
+      self.class.untrack(self)
+    end
+  end
+end

data/lib/active_usage/tags.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class Tags
+    KEY = :activeusage_tags
+
+    def initialize(tags)
+      @tags = tags
+    end
+
+    def tag(**tags)
+      ActiveSupport::IsolatedExecutionState[KEY] = current.merge(tags)
+    end
+
+    def current
+      ActiveSupport::IsolatedExecutionState[KEY] || @tags
+    end
+
+    def flush
+      ActiveSupport::IsolatedExecutionState[KEY] = @tags
+    end
+  end
+end

data/lib/active_usage/tracker.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class Tracker
+    def initialize(name, tags)
+      @name = name
+      @tags = tags
+      @started_at = Time.current
+    end
+
+    def call(&)
+      Instrumentation::RuntimeState.clear_sql_state
+      result = ActiveSupport::Notifications.subscribed(sql_listener, "sql.active_record", &)
+      ActiveUsage.record(**attributes)
+      result
+    ensure
+      Instrumentation::RuntimeState.clear_sql_state
+    end
+
+    private
+
+    def sql_listener
+      lambda do |_name, started, finished, _id, payload|
+        next if payload[:cached]
+
+        Instrumentation::RuntimeState.add_sql_event(
+          payload,
+          started_at: started,
+          finished_at: finished
+        )
+      end
+    end
+
+    def attributes
+      {
+        type: :task,
+        name: @name,
+        started_at: @started_at,
+        finished_at: Time.current,
+        tags: @tags,
+        sql_queries: Instrumentation::RuntimeState.consume_sql_queries
+      }
+    end
+  end
+end

data/lib/active_usage/type/sql_queries.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  module Type
+    class SqlQueries < ActiveModel::Type::Value
+      def cast(value)
+        return [] unless value.is_a?(::Array)
+
+        value
+      end
+    end
+  end
+end
+
+ActiveModel::Type.register(:sql_queries, ActiveUsage::Type::SqlQueries)

data/lib/active_usage/type/tags.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  module Type
+    class Tags < ActiveModel::Type::Value
+      def cast(value)
+        return nil unless value.is_a?(::Hash)
+
+        value.transform_keys(&:to_sym)
+      end
+    end
+  end
+end
+
+ActiveModel::Type.register(:tags, ActiveUsage::Type::Tags)

data/lib/active_usage/version.rb

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

data/lib/active_usage/window_started_at.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class WindowStartedAt
+    def initialize(finished_at, size)
+      @finished_at = finished_at
+      @size = size
+    end
+
+    def call
+      Time.at(epoch - (epoch % @size))
+    end
+
+    private
+
+    def epoch
+      @epoch ||= @finished_at.to_i
+    end
+  end
+end

data/lib/active_usage/worker.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveUsage
+  class Worker
+    def initialize(interval, &block)
+      @interval = interval
+      @block = block
+      @mutex = Mutex.new
+      @running = true
+      start!
+    end
+
+    def stop!
+      @mutex.synchronize { @running = false }
+    end
+
+    def join(timeout)
+      @thread&.join(timeout)
+    end
+
+    private
+
+    def running?
+      @mutex.synchronize { @running }
+    end
+
+    def start!
+      @thread = Thread.new do
+        Thread.current.name = "activeusage.worker" if Thread.current.respond_to?(:name=)
+        tick while running?
+      end
+    end
+
+    def tick
+      sleep @interval
+      @block.call
+    rescue StandardError => e
+      ActiveUsage.logger.error("[ActiveUsage::Worker] #{e.class}: #{e.message}")
+    end
+  end
+end

data/lib/active_usage.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support"
+
+require "json"
+require "net/http"
+require "uri"
+require "logger"
+
+require_relative "active_usage/version"
+require_relative "active_usage/configuration"
+require_relative "active_usage/type/tags"
+require_relative "active_usage/type/sql_queries"
+require_relative "active_usage/event"
+require_relative "active_usage/recorder"
+require_relative "active_usage/tags"
+require_relative "active_usage/window_started_at"
+require_relative "active_usage/event_queue"
+require_relative "active_usage/worker"
+require_relative "active_usage/store"
+require_relative "active_usage/adapters/base"
+require_relative "active_usage/adapters/http"
+require_relative "active_usage/tracker"
+require_relative "active_usage/middleware"
+require_relative "active_usage/instrumentation/active_job_hook"
+require_relative "active_usage/instrumentation/runtime_state"
+require_relative "active_usage/instrumentation/subscriber"
+
+# Top-level namespace for the ActiveUsage gem.
+module ActiveUsage
+  @configuration_mutex = Mutex.new
+  @store_mutex = Mutex.new
+  @tags_mutex = Mutex.new
+
+  class << self
+    def configuration
+      @configuration || @configuration_mutex.synchronize { @configuration ||= Configuration.new }
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def logger
+      configuration.logger
+    end
+
+    def record(type:, name:, started_at:, finished_at:, **attributes)
+      Recorder.new(
+        type: type,
+        name: name,
+        started_at: started_at,
+        finished_at: finished_at,
+        tags: tags.current.merge(attributes.delete(:tags) || {}),
+        window_started_at: WindowStartedAt.new(finished_at, configuration.window_size).call,
+        **attributes
+      ).call(store)
+    end
+
+    def track(name, tags: {}, &)
+      Tracker.new(name, tags).call(&)
+    end
+
+    def tags
+      @tags || @tags_mutex.synchronize { @tags ||= Tags.new(configuration.tags) }
+    end
+
+    def store
+      @store || @store_mutex.synchronize { @store ||= Store.new(configuration.adapter) }
+    end
+  end
+end
+
+require "active_usage/railtie" if defined?(Rails::Railtie)

data/lib/activeusage.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "active_usage"

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: activeusage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tomasz Kowalewski
+bindir: bin
+cert_chain: []
+date: 2026-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: ActiveUsage turns runtime signals into practical cost estimates for requests,
+  jobs, and tasks.
+email:
+- me@tkowalewski.pl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/active_usage.rb
+- lib/active_usage/adapters/base.rb
+- lib/active_usage/adapters/http.rb
+- lib/active_usage/configuration.rb
+- lib/active_usage/event.rb
+- lib/active_usage/event_queue.rb
+- lib/active_usage/instrumentation/active_job_hook.rb
+- lib/active_usage/instrumentation/runtime_state.rb
+- lib/active_usage/instrumentation/subscriber.rb
+- lib/active_usage/middleware.rb
+- lib/active_usage/railtie.rb
+- lib/active_usage/recorder.rb
+- lib/active_usage/store.rb
+- lib/active_usage/tags.rb
+- lib/active_usage/tracker.rb
+- lib/active_usage/type/sql_queries.rb
+- lib/active_usage/type/tags.rb
+- lib/active_usage/version.rb
+- lib/active_usage/window_started_at.rb
+- lib/active_usage/worker.rb
+- lib/activeusage.rb
+homepage: https://activeusage.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://activeusage.com
+  source_code_uri: https://github.com/ActiveUsage/activeusage/tree/0.1.0
+  changelog_uri: https://github.com/ActiveUsage/activeusage/tree/0.1.0/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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: 3.6.2
+specification_version: 4
+summary: Cost observability core for Ruby and Rails workloads.
+test_files: []