llm_cost_tracker 0.5.3 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3fe81fdf7b12f977d7dfc4aa86f629e8b5ad6e099100bfbfe1b18507db17fff
-  data.tar.gz: dffe0c0ebeb30fa111273b654141ee06e1275426846796b1749435429da3414f
+  metadata.gz: 6942269ea8e3ce5f22bb30a1dc6f6c73ee056b33f4f5d7697d1749ce5742ca93
+  data.tar.gz: 1b0712cfcbea56ee0e03dd1cb6c400969fc485c5648f75616140a62f6e82fc02
 SHA512:
-  metadata.gz: 4849f0d0b09d640ed3a902bbc19a975e576b0539d2c71eac3165199eed196ecd88f249ff1d571c43b2686d59466dde26a0467f984c2cbb7804a5f771e184df31
-  data.tar.gz: 8aa17efc9dd68b1489cdc69351a67fe2398c35720750cf1440f215bceeef0392c9f3af1d41ebd444ddcd9876c2c1e612ea50d6403fb7f650735fc9d9161a2a85
+  metadata.gz: 9793cc211dd08669deecf4a1d6a242ec4f2fff3fc41922472d158002731f4db40d618163d6fb054eeb36cae4e8aa708a0055a0fe1820faf88081b26de407107a
+  data.tar.gz: 05ed21f8309b16475b4ca7a0a938c999336f0ebb09baf897225422c69dd8e7e81f73ef01e69ff2d4c80d392f49230c212a87ec5c925c6e242b24942c5369f37f

data/CHANGELOG.md

@@ -4,6 +4,42 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-04-29
+
+### Fixed
+
+- Exclude repository documentation from the published gem package.
+
+## [0.6.0] - 2026-04-29
+
+### Added
+
+- Durable ActiveRecord ingestion through `llm_cost_tracker_inbox_events` and `llm_cost_tracker_ingestor_leases`.
+- `llm_cost_tracker:add_ingestion` generator for upgrading existing ActiveRecord installs.
+- `LlmCostTracker.flush!` and `LlmCostTracker.shutdown!` for draining or stopping durable ingestion.
+- Doctor diagnostics for missing durable ingestion schema, stale pending inbox rows, and quarantined inbox rows.
+- PostgreSQL and MySQL smoke checks for ActiveRecord durable ingestion.
+
+### Changed
+
+- Fresh ActiveRecord installs now include durable ingestion tables, event IDs, and production indexes.
+- ActiveRecord budget totals now read stored period rollups plus pending inbox totals while durable ingestion is enabled.
+- ActiveRecord writes now use a durable inbox before batching ledger inserts and period rollup updates when ingestion tables are present.
+- Pricing lookup now caches normalized runtime price tables and model matches by configuration generation.
+- Stream capture now estimates buffered event size without serializing every captured event.
+- CSV export now selects only exported columns instead of loading full ActiveRecord objects.
+
+### Fixed
+
+- ActiveRecord rollups no longer double-count retried events when duplicate event IDs race across workers.
+- Invalid inbox rows are retried and quarantined without blocking healthy rows behind them.
+- Idle ingestors no longer acquire the leader lease while the inbox is empty.
+- ActiveRecord inbox writes now fail honestly when a separate connection is unavailable inside a caller transaction.
+- Ingestor shutdown/reset no longer lets an old sleeping thread resume as a second local ingestor.
+- `flush!` now returns `false` instead of raising when its timeout expires during ingestion.
+- ActiveRecord adapter family detection now works through known adapter class ancestry with an adapter-name fallback.
+- CSV export now emits `{}` for invalid stored tag payloads.
+
 ## [0.5.3] - 2026-04-28
 
 ### Added

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "csv"
+require "json"
 
 module LlmCostTracker
   class CallsController < ApplicationController
@@ -54,32 +55,45 @@ module LlmCostTracker
     end
 
     def render_csv(relation)
-      latency = LlmApiCall.latency_column?
+      fields = csv_fields
       CSV.generate do |csv|
-        headers = %w[tracked_at provider model input_tokens output_tokens total_tokens total_cost]
-        headers << "latency_ms" if latency
-        headers << "provider_response_id" if LlmApiCall.provider_response_id_column?
-        headers << "tags"
-        csv << headers
-
-        relation.each do |call|
-          row = [
-            call.tracked_at&.utc&.iso8601,
-            csv_safe(call.provider),
-            csv_safe(call.model),
-            call.input_tokens,
-            call.output_tokens,
-            call.total_tokens,
-            call.total_cost
-          ]
-          row << call.latency_ms if latency
-          row << csv_safe(call.provider_response_id) if LlmApiCall.provider_response_id_column?
-          row << csv_safe(call.parsed_tags.to_json)
-          csv << row
+        csv << fields.map(&:to_s)
+
+        relation.pluck(*fields).each do |values|
+          csv << fields.zip(values).map { |field, value| csv_value(field, value) }
         end
       end
     end
 
+    def csv_fields
+      fields = %i[tracked_at provider model input_tokens output_tokens total_tokens total_cost]
+      fields << :latency_ms if LlmApiCall.latency_column?
+      fields << :provider_response_id if LlmApiCall.provider_response_id_column?
+      fields << :tags
+      fields
+    end
+
+    def csv_value(field, value)
+      case field
+      when :tracked_at
+        value&.utc&.iso8601
+      when :provider, :model, :provider_response_id
+        csv_safe(value)
+      when :tags
+        csv_safe(csv_tags(value))
+      else
+        value
+      end
+    end
+
+    def csv_tags(value)
+      return value.transform_keys(&:to_s).to_json if value.is_a?(Hash)
+
+      JSON.parse(value || "{}").to_json
+    rescue JSON::ParserError
+      "{}"
+    end
+
     def csv_safe(value)
       return value if value.nil?
 

data/app/services/llm_cost_tracker/dashboard/overview_stats.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "llm_cost_tracker/storage/active_record_store"
+
 module LlmCostTracker
   module Dashboard
     OverviewStatsData = Data.define(
@@ -77,7 +79,7 @@ module LlmCostTracker
           now = Time.now.utc
           month_start = now.beginning_of_month
           month_end = now.end_of_month
-          spent = LlmCostTracker::LlmApiCall.this_month.total_cost
+          spent = LlmCostTracker::Storage::ActiveRecordStore.monthly_total(time: now)
           elapsed_seconds = now - month_start
           total_seconds = month_end - month_start
           projected_spent = if spent.zero? || !elapsed_seconds.positive?

data/app/services/llm_cost_tracker/dashboard/tag_key_explorer.rb

@@ -42,11 +42,10 @@ module LlmCostTracker
       end
 
       def build_sql
-        case connection.adapter_name
-        when /postgres/i then postgresql_sql
-        when /mysql/i    then mysql_sql
-        else                  sqlite_sql
-        end
+        return postgresql_sql if ActiveRecordAdapter.postgresql?(connection)
+        return mysql_sql if ActiveRecordAdapter.mysql?(connection)
+
+        sqlite_sql
       end
 
       def mysql_sql

data/lib/llm_cost_tracker/active_record_adapter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module ActiveRecordAdapter
+    MYSQL_ADAPTERS = %w[
+      ActiveRecord::ConnectionAdapters::AbstractMysqlAdapter
+      ActiveRecord::ConnectionAdapters::Mysql2Adapter
+      ActiveRecord::ConnectionAdapters::TrilogyAdapter
+    ].freeze
+    POSTGRESQL_ADAPTERS = %w[
+      ActiveRecord::ConnectionAdapters::PostgreSQLAdapter
+    ].freeze
+    SQLITE_ADAPTERS = %w[
+      ActiveRecord::ConnectionAdapters::SQLite3Adapter
+    ].freeze
+    MYSQL_PATTERN = /mysql|trilogy|mariadb/i
+    POSTGRESQL_PATTERN = /postgres/i
+    SQLITE_PATTERN = /sqlite/i
+
+    class << self
+      def mysql?(value) = adapter_instance?(value, MYSQL_ADAPTERS) || adapter_name(value).match?(MYSQL_PATTERN)
+
+      def postgresql?(value)
+        adapter_instance?(value, POSTGRESQL_ADAPTERS) || adapter_name(value).match?(POSTGRESQL_PATTERN)
+      end
+
+      def sqlite?(value) = adapter_instance?(value, SQLITE_ADAPTERS) || adapter_name(value).match?(SQLITE_PATTERN)
+
+      private
+
+      def adapter_instance?(value, class_names)
+        class_names.any? do |class_name|
+          adapter_class = constantize(class_name)
+          adapter_class && value.is_a?(adapter_class)
+        end
+      end
+
+      def constantize(name)
+        name.split("::").reduce(Object) { |namespace, part| namespace.const_get(part, false) }
+      rescue NameError
+        nil
+      end
+
+      def adapter_name(value)
+        value.respond_to?(:adapter_name) ? value.adapter_name.to_s : value.to_s
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/doctor/ingestion_check.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "time"
+
+module LlmCostTracker
+  class Doctor
+    class IngestionCheck
+      PENDING_AGE_WARNING_SECONDS = 60
+
+      def self.call(check_class)
+        new(check_class).call
+      end
+
+      def initialize(check_class)
+        @check_class = check_class
+      end
+
+      def call
+        return unless active_record_storage? && llm_api_calls_table?
+
+        missing = missing_parts
+        if missing.empty?
+          quarantined = quarantined_count
+          if quarantined.positive?
+            return check_class.new(:warn, "durable ingestion", "#{quarantined} inbox events quarantined after retries")
+          end
+
+          pending = pending_snapshot
+          if stale_pending?(pending)
+            return check_class.new(
+              :warn,
+              "durable ingestion",
+              "#{pending.fetch(:count)} inbox events pending; oldest pending age #{pending_age(pending).round}s"
+            )
+          end
+
+          return check_class.new(:ok, "durable ingestion", "inbox and ingestor lease tables available")
+        end
+
+        check_class.new(
+          :warn,
+          "durable ingestion",
+          "missing #{missing.join(', ')}; run bin/rails generate llm_cost_tracker:add_ingestion && bin/rails db:migrate"
+        )
+      end
+
+      private
+
+      attr_reader :check_class
+
+      def missing_parts
+        [
+          column_names("llm_api_calls").include?("event_id") ? nil : "llm_api_calls.event_id",
+          table_exists?("llm_cost_tracker_inbox_events") ? nil : "llm_cost_tracker_inbox_events",
+          table_exists?("llm_cost_tracker_ingestor_leases") ? nil : "llm_cost_tracker_ingestor_leases"
+        ].compact
+      end
+
+      def active_record_storage? = LlmCostTracker.configuration.storage_backend == :active_record
+
+      def llm_api_calls_table? = table_exists?("llm_api_calls")
+
+      def table_exists?(name)
+        LlmCostTracker::LlmApiCall.connection.data_source_exists?(name)
+      rescue StandardError
+        false
+      end
+
+      def column_names(table) = LlmCostTracker::LlmApiCall.connection.columns(table).map(&:name)
+
+      def quarantined_count
+        return 0 unless table_exists?("llm_cost_tracker_inbox_events")
+
+        LlmCostTracker::LlmApiCall.connection.select_value(quarantined_sql).to_i
+      rescue StandardError
+        0
+      end
+
+      def quarantined_sql
+        table = LlmCostTracker::LlmApiCall.connection.quote_table_name("llm_cost_tracker_inbox_events")
+        "SELECT COUNT(*) FROM #{table} WHERE attempts >= #{max_attempts}"
+      end
+
+      def pending_snapshot
+        row = LlmCostTracker::LlmApiCall.connection.select_one(pending_sql) || {}
+        {
+          count: row.fetch("pending_count").to_i,
+          oldest_at: row["oldest_created_at"] && Time.parse(row.fetch("oldest_created_at").to_s).utc
+        }
+      rescue StandardError
+        { count: 0, oldest_at: nil }
+      end
+
+      def pending_sql
+        table = LlmCostTracker::LlmApiCall.connection.quote_table_name("llm_cost_tracker_inbox_events")
+        "SELECT COUNT(*) AS pending_count, MIN(created_at) AS oldest_created_at " \
+          "FROM #{table} WHERE attempts < #{max_attempts}"
+      end
+
+      def stale_pending?(pending)
+        pending.fetch(:count).positive? &&
+          pending.fetch(:oldest_at) &&
+          pending_age(pending) >= PENDING_AGE_WARNING_SECONDS
+      end
+
+      def pending_age(pending) = Time.now.utc - pending.fetch(:oldest_at)
+
+      def max_attempts
+        if defined?(LlmCostTracker::Storage::ActiveRecordInbox::MAX_ATTEMPTS)
+          LlmCostTracker::Storage::ActiveRecordInbox::MAX_ATTEMPTS
+        else
+          5
+        end
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/doctor.rb

@@ -2,6 +2,7 @@
 
 require_relative "price_freshness"
 require_relative "doctor/capture_check"
+require_relative "doctor/ingestion_check"
 
 module LlmCostTracker
   class Doctor
@@ -45,6 +46,7 @@ module LlmCostTracker
         table_check,
         column_check,
         period_totals_check,
+        IngestionCheck.call(Check),
         prices_check,
         calls_check
       ].compact

data/lib/llm_cost_tracker/event.rb

@@ -2,6 +2,7 @@
 
 module LlmCostTracker
   Event = Data.define(
+    :event_id,
     :provider,
     :model,
     :input_tokens,

data/lib/llm_cost_tracker/generators/llm_cost_tracker/add_ingestion_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class AddIngestionGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to add durable ActiveRecord ingestion"
+
+      def create_migration_file
+        migration_template(
+          "add_ingestion_to_llm_cost_tracker.rb.erb",
+          "db/migrate/add_ingestion_to_llm_cost_tracker.rb"
+        )
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_ingestion_to_llm_cost_tracker.rb.erb

@@ -0,0 +1,33 @@
+class AddIngestionToLlmCostTracker < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :llm_api_calls, :event_id, :string unless column_exists?(:llm_api_calls, :event_id)
+    add_index :llm_api_calls, :event_id, unique: true if column_exists?(:llm_api_calls, :event_id) &&
+                                                         !index_exists?(:llm_api_calls, :event_id)
+
+    create_table :llm_cost_tracker_inbox_events do |t|
+      t.string   :event_id, null: false
+      t.decimal  :total_cost, precision: 20, scale: 8
+      t.datetime :tracked_at, null: false
+      t.text     :payload, null: false
+      t.datetime :locked_at
+      t.string   :locked_by
+      t.integer  :attempts, null: false, default: 0
+      t.text     :last_error
+
+      t.timestamps
+    end unless table_exists?(:llm_cost_tracker_inbox_events)
+
+    create_table :llm_cost_tracker_ingestor_leases do |t|
+      t.string   :name, null: false
+      t.string   :locked_by
+      t.datetime :locked_until
+
+      t.timestamps
+    end unless table_exists?(:llm_cost_tracker_ingestor_leases)
+
+    add_index :llm_cost_tracker_inbox_events, :event_id, unique: true unless index_exists?(:llm_cost_tracker_inbox_events, :event_id)
+    add_index :llm_cost_tracker_inbox_events, :tracked_at unless index_exists?(:llm_cost_tracker_inbox_events, :tracked_at)
+    add_index :llm_cost_tracker_inbox_events, [:locked_at, :id] unless index_exists?(:llm_cost_tracker_inbox_events, [:locked_at, :id])
+    add_index :llm_cost_tracker_ingestor_leases, :name, unique: true unless index_exists?(:llm_cost_tracker_ingestor_leases, :name)
+  end
+end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_period_totals_to_llm_cost_tracker.rb.erb

@@ -1,3 +1,5 @@
+require "llm_cost_tracker/active_record_adapter"
+
 class AddPeriodTotalsToLlmCostTracker < ActiveRecord::Migration<%= migration_version %>
   def up
     create_table :llm_cost_tracker_period_totals do |t|
@@ -73,10 +75,9 @@ class AddPeriodTotalsToLlmCostTracker < ActiveRecord::Migration<%= migration_ver
   end
 
   def day_bucket_sql
-    case connection.adapter_name
-    when /postgres/i
+    if postgresql?
       "DATE_TRUNC('day', tracked_at)::date"
-    when /mysql/i
+    elsif mysql?
       "DATE(tracked_at)"
     else
       "date(tracked_at)"
@@ -84,13 +85,20 @@ class AddPeriodTotalsToLlmCostTracker < ActiveRecord::Migration<%= migration_ver
   end
 
   def month_bucket_sql
-    case connection.adapter_name
-    when /postgres/i
+    if postgresql?
       "DATE_TRUNC('month', tracked_at)::date"
-    when /mysql/i
+    elsif mysql?
       "DATE_FORMAT(tracked_at, '%Y-%m-01')"
     else
       "strftime('%Y-%m-01', tracked_at)"
     end
   end
+
+  def postgresql?
+    LlmCostTracker::ActiveRecordAdapter.postgresql?(connection)
+  end
+
+  def mysql?
+    LlmCostTracker::ActiveRecordAdapter.mysql?(connection)
+  end
 end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_streaming_to_llm_api_calls.rb.erb

@@ -2,23 +2,19 @@ class AddStreamingToLlmApiCalls < ActiveRecord::Migration<%= migration_version %
   def up
     unless column_exists?(:llm_api_calls, :stream)
       add_column :llm_api_calls, :stream, :boolean, null: false, default: false
-      add_index  :llm_api_calls, :stream
     end
 
     unless column_exists?(:llm_api_calls, :usage_source)
       add_column :llm_api_calls, :usage_source, :string
-      add_index  :llm_api_calls, :usage_source
     end
   end
 
   def down
     if column_exists?(:llm_api_calls, :usage_source)
-      remove_index  :llm_api_calls, :usage_source if index_exists?(:llm_api_calls, :usage_source)
       remove_column :llm_api_calls, :usage_source
     end
 
     if column_exists?(:llm_api_calls, :stream)
-      remove_index  :llm_api_calls, :stream if index_exists?(:llm_api_calls, :stream)
       remove_column :llm_api_calls, :stream
     end
   end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_api_calls.rb.erb

@@ -1,6 +1,9 @@
+require "llm_cost_tracker/active_record_adapter"
+
 class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
   def change
     create_table :llm_api_calls do |t|
+      t.string  :event_id,      null: false
       t.string  :provider,      null: false
       t.string  :model,         null: false
       t.integer :input_tokens,  null: false, default: 0
@@ -37,19 +40,43 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
+    create_table :llm_cost_tracker_inbox_events do |t|
+      t.string   :event_id, null: false
+      t.decimal  :total_cost, precision: 20, scale: 8
+      t.datetime :tracked_at, null: false
+      t.text     :payload, null: false
+      t.datetime :locked_at
+      t.string   :locked_by
+      t.integer  :attempts, null: false, default: 0
+      t.text     :last_error
+
+      t.timestamps
+    end
+
+    create_table :llm_cost_tracker_ingestor_leases do |t|
+      t.string   :name, null: false
+      t.string   :locked_by
+      t.datetime :locked_until
+
+      t.timestamps
+    end
+
+    add_index :llm_api_calls, :event_id, unique: true
     add_index :llm_api_calls, :tracked_at
     add_index :llm_api_calls, [:provider, :tracked_at]
     add_index :llm_api_calls, [:model, :tracked_at]
-    add_index :llm_api_calls, :stream
-    add_index :llm_api_calls, :usage_source
     add_index :llm_api_calls, :provider_response_id
     add_index :llm_api_calls, :tags, using: :gin if postgresql?
     add_index :llm_cost_tracker_period_totals, [:period, :period_start], unique: true
+    add_index :llm_cost_tracker_inbox_events, :event_id, unique: true
+    add_index :llm_cost_tracker_inbox_events, :tracked_at
+    add_index :llm_cost_tracker_inbox_events, [:locked_at, :id]
+    add_index :llm_cost_tracker_ingestor_leases, :name, unique: true
   end
 
   private
 
   def postgresql?
-    connection.adapter_name.downcase.include?("postgres")
+    LlmCostTracker::ActiveRecordAdapter.postgresql?(connection)
   end
 end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/initializer.rb.erb

@@ -4,7 +4,7 @@ LlmCostTracker.configure do |config|
   # Set to false to temporarily disable tracking without removing middleware.
   config.enabled = true
 
-  # :active_record stores events in llm_api_calls for dashboards, reports, and shared budgets.
+  # :active_record captures events into a durable inbox and ingests them into llm_api_calls.
   # Other options: :log for local logging, :custom for your own storage callable.
   config.storage_backend = :active_record
 

data/lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_llm_api_call_tags_to_jsonb.rb.erb

@@ -1,3 +1,5 @@
+require "llm_cost_tracker/active_record_adapter"
+
 class UpgradeLlmApiCallTagsToJsonb < ActiveRecord::Migration<%= migration_version %>
   def up
     unless postgresql?
@@ -32,7 +34,7 @@ class UpgradeLlmApiCallTagsToJsonb < ActiveRecord::Migration<%= migration_versio
   private
 
   def postgresql?
-    connection.adapter_name.downcase.include?("postgres")
+    LlmCostTracker::ActiveRecordAdapter.postgresql?(connection)
   end
 
   def tags_jsonb?

data/lib/llm_cost_tracker/inbox_event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module LlmCostTracker
+  class InboxEvent < ActiveRecord::Base
+    self.table_name = "llm_cost_tracker_inbox_events"
+  end
+end

data/lib/llm_cost_tracker/ingestor_lease.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module LlmCostTracker
+  class IngestorLease < ActiveRecord::Base
+    self.table_name = "llm_cost_tracker_ingestor_leases"
+  end
+end

data/lib/llm_cost_tracker/period_grouping.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "active_record_adapter"
+
 module LlmCostTracker
   module PeriodGrouping
     PERIOD_FORMATS = {
@@ -34,10 +36,9 @@ module LlmCostTracker
       column = period_column_expression(column)
       formats = PERIOD_FORMATS.fetch(period)
 
-      case connection.adapter_name
-      when /postgres/i
+      if ActiveRecordAdapter.postgresql?(connection)
         postgres_period_expression(period, column, formats)
-      when /mysql/i
+      elsif ActiveRecordAdapter.mysql?(connection)
         "DATE_FORMAT(#{column}, #{connection.quote(formats.fetch(:mysql))})"
       else
         "strftime(#{connection.quote(formats.fetch(:sqlite))}, #{column})"