llm_cost_tracker 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93ef8bc5c6bc0e850398b7555499a4667d1cc3d8ba2328c1fb926204a794a5a7
-  data.tar.gz: e7208b7bf518332040837498b5de7d1e5e6c761a276d6fb732d14133d38d8c74
+  metadata.gz: b966913d302d5c5c3466615d1fa3983855c241f6cd9e3e26558c0fcc5fc4e7d5
+  data.tar.gz: 52804e702d5f01e5a4d247e8b50e601dede2b328bd7075c68ffd5f472b3b0d58
 SHA512:
-  metadata.gz: 5d19b85e0a4398332a0161f75bc561b79c6ebf12546fe21013b12f2b7f5ff931179fcb8d5610faccd4d84063bf10f4297bd1688df04c24e41ffb63d4ff38b851
-  data.tar.gz: e7b4f3a2164cc9f6e9545e123fe4aeabac356ab66becfc94466f8f25d54329ed5af4056339cfda1c71e20bcba1c4de30a9922ff3b7b5664528bde515834e19f1
+  metadata.gz: 609ba1a18be86dce0b567b2ea33b3f3123da88683f0c65d9aef780f2e4854d1dde6686adfa505fc154d13da6dd6cb2b31d9f38c303de5fb22f6fda65c7f44aa7
+  data.tar.gz: de372e0940b4cfc400dacfc6dbf9e00f256c6944209da8cceaadd20a318b8c7aa8982d5190e21d38640ad20d04cc86400a4e872ec640189796e045acf1f7dfad

data/CHANGELOG.md

@@ -4,6 +4,33 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-04-24
+
+### Added
+
+- Monthly rollup totals for ActiveRecord budget checks, plus `llm_cost_tracker:add_monthly_totals` for upgrading existing installs.
+
+### Changed
+
+- ActiveRecord monthly totals now update through a single atomic upsert.
+- Faraday stream capture overflow now records `usage_source: "unknown"` instead of dropping the tracked event.
+- Budget `:notify` callbacks now fire only on the first event that crosses the monthly limit.
+
+### Fixed
+
+- Treat `config.enabled = false` as a global kill switch for direct `track` and `track_stream` calls too.
+- Deduplicate unknown-pricing warnings per model.
+- Detect streaming requests from parsed JSON instead of raw body substring matching.
+- Cap automatic SSE capture to avoid unbounded memory growth on large streaming responses.
+- Warn that the generated PostgreSQL `tags -> jsonb` upgrade migration rewrites large tables and should run in a maintenance window.
+
+## [0.3.2] - 2026-04-22
+
+### Added
+
+- Test coverage reporting via SimpleCov with LCOV upload to Codecov from CI.
+- Repository governance files: `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CONTRIBUTING.md`, and GitHub issue templates.
+
 ## [0.3.1] - 2026-04-22
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, as its code of conduct. The full text is available at:
+
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>
+
+## Our pledge
+
+We as contributors and maintainers pledge to make participation in this project a welcoming, respectful, and inclusive experience for everyone.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (issues, pull requests, discussions, commit messages, review comments) and in public spaces when an individual is representing the project.
+
+## Reporting
+
+Instances of unacceptable behavior may be reported to the project maintainer at **sergey@mm.st**. All reports will be reviewed and investigated promptly and fairly. The maintainer is obligated to respect the privacy and safety of the reporter of any incident.
+
+## Enforcement
+
+Maintainers are responsible for clarifying and enforcing the standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, or harmful. This may include warnings, temporary bans, or permanent removal from project participation.
+
+For the full set of community standards, enforcement guidelines, and attribution, see the canonical document linked above.

data/README.md

@@ -4,14 +4,70 @@
 
 [![Gem Version](https://img.shields.io/gem/v/llm_cost_tracker.svg)](https://rubygems.org/gems/llm_cost_tracker)
 [![CI](https://github.com/sergey-homenko/llm_cost_tracker/actions/workflows/ruby.yml/badge.svg)](https://github.com/sergey-homenko/llm_cost_tracker/actions)
+[![codecov](https://codecov.io/gh/sergey-homenko/llm_cost_tracker/branch/main/graph/badge.svg)](https://codecov.io/gh/sergey-homenko/llm_cost_tracker)
+
+Requires Ruby 3.3+, Rails/ActiveRecord 7.1+, and Faraday 2.0+.
+Core tracking works without Rails; the mounted dashboard requires Rails 7.1+.
 
 ## Why
 
 Every Rails app with LLM integrations eventually runs into the same question: where did that invoice come from? Full observability platforms like Langfuse and Helicone solve a broader set of problems; sometimes you just need a small Rails-native ledger in your own database.
 
-`llm_cost_tracker` is built for that. It plugs into Faraday or lets you record usage explicitly with `track` / `track_stream`, looks up pricing locally, and writes an event. You end up with a ledger you can query with plain ActiveRecord, slice by any tag dimension, and optionally surface on a built-in dashboard. No proxy, no SaaS, no separate service to run.
+## What You Get
+
+- A local ActiveRecord ledger of provider, model, tokens, cost, latency, tags, streaming usage, and provider response IDs
+- Faraday middleware plus explicit `track` / `track_stream` helpers for non-Faraday clients
+- Server-rendered Rails dashboard with overview, calls, tags, CSV export, and data-quality pages
+- Local pricing snapshots, price sync tasks, and budget guardrails
+- Prompt and response bodies are never persisted
+
+## Dashboard
+
+LLM Cost Tracker ships with an optional server-rendered Rails Engine dashboard for spend review, attribution, and data quality checks.
+
+![LLM Cost Tracker dashboard](docs/dashboard-overview.png)
 
-It is not a tracing platform, prompt CMS, eval system, or gateway. The goal is to answer _"what did this app spend on LLM APIs, and where did that spend come from?"_ clearly enough to make spend review routine.
+The overview page includes spend trend, budget status, provider breakdown, top models, and filterable slices. The engine also includes Calls, Tags, and Data Quality pages. Plain ERB, no JavaScript bundle.
+
+## Quickstart
+
+```ruby
+gem "llm_cost_tracker"
+```
+
+```bash
+bin/rails generate llm_cost_tracker:install
+bin/rails db:migrate
+```
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.storage_backend = :active_record
+  config.default_tags = { app: "my_app", environment: Rails.env }
+end
+
+OpenAI.configure do |config|
+  config.access_token = ENV["OPENAI_API_KEY"]
+  config.faraday do |f|
+    f.use :llm_cost_tracker, tags: -> { { user_id: Current.user&.id, feature: "chat" } }
+  end
+end
+```
+
+```ruby
+mount LlmCostTracker::Engine => "/llm-costs"
+```
+
+After that, LLM Cost Tracker starts recording calls into `llm_api_calls` and the dashboard becomes available at `/llm-costs`.
+Protect the mounted engine with your application's authentication before exposing it outside development.
+
+## Tradeoffs
+
+- Self-hosted ledger first: no proxy, no SaaS, no separate service to operate
+- Best-effort pricing for spend review and attribution, not invoice-grade billing
+- No prompt or response body storage
+- No built-in auth on the mounted dashboard
+- Use `:active_record` when you want shared dashboards and budget checks across Puma workers and Sidekiq processes
 
 ## Installation
 
@@ -287,13 +343,16 @@ On other adapters tags fall back to JSON in a text column. `by_tag` uses JSONB c
 Upgrade an existing install:
 
 ```bash
+bin/rails generate llm_cost_tracker:add_monthly_totals   # shared monthly budget rollups
 bin/rails generate llm_cost_tracker:upgrade_tags_to_jsonb   # PG: text → jsonb + GIN
 bin/rails generate llm_cost_tracker:upgrade_cost_precision  # widen cost columns
 bin/rails generate llm_cost_tracker:add_latency_ms
 bin/rails db:migrate
 ```
 
-## Dashboard (optional)
+On PostgreSQL, the generated `upgrade_tags_to_jsonb` migration rewrites `llm_api_calls`. Run it during a maintenance window on large tables, or replace it with a two-phase backfill for zero-downtime deploys.
+
+## Mounting the dashboard
 
 Optional Rails Engine. Plain ERB, no JavaScript framework, no asset pipeline required. Requires Rails 7.1+; the core middleware works without Rails.
 
@@ -315,7 +374,7 @@ Routes (GET-only; CSV export included):
 - `/llm-costs/tags/:key` — breakdown by values of a given tag key
 - `/llm-costs/data_quality` — unknown pricing share, untagged calls, missing latency
 
-> ⚠️ **No built-in auth.** Tags carry whatever your app puts in them. Protect the mount point with your application's authentication.
+No built-in auth is included. Tags carry whatever your app puts in them, so protect the mount point with your application's authentication.
 
 ### Basic auth
 
@@ -381,20 +440,26 @@ Configured hosts are parsed using the OpenAI-compatible usage shape (`prompt_tok
 For providers with a non-OpenAI usage shape:
 
 ```ruby
+require "uri"
+
 class AcmeParser < LlmCostTracker::Parsers::Base
   def match?(url)
-    url.to_s.include?("api.acme-llm.example")
+    uri = URI.parse(url.to_s)
+    uri.host == "api.acme-llm.example" && uri.path == "/v1/generate"
+  rescue URI::InvalidURIError
+    false
   end
 
   def parse(request_url, request_body, response_status, response_body)
     return nil unless response_status == 200
 
-    usage = safe_json_parse(response_body)&.dig("usage")
+    payload = safe_json_parse(response_body)
+    usage = payload&.dig("usage")
     return nil unless usage
 
     LlmCostTracker::ParsedUsage.build(
       provider: "acme",
-      model: safe_json_parse(response_body)["model"],
+      model: payload["model"],
       input_tokens: usage["input"] || 0,
       output_tokens: usage["output"] || 0
     )
@@ -420,9 +485,12 @@ Endpoints: OpenAI Chat Completions / Responses / Completions / Embeddings; OpenA
 
 ## Safety
 
+**By design, `llm_cost_tracker` never persists prompt or response content.** The only data stored per call is the metadata needed for a cost ledger (provider, model, token counts, cost, latency, tags, provider response ID, HTTP status, and a timestamp). Tags carry whatever your application passes in — treat them as user-controlled input and avoid putting request bodies, completions, or secrets into them.
+
 - No external HTTP calls at request-tracking time.
 - No prompt or response bodies stored.
 - Faraday responses not modified.
+- Authorization headers and API keys are never stored or logged.
 - Storage failures non-fatal by default (`storage_error_behavior = :warn`).
 - Budget and unknown-pricing errors are raised only when you opt in.
 

data/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Supported versions
+
+The gem is pre-1.0. Only the latest released version receives security fixes — please upgrade rather than expecting backports to older releases.
+
+## Reporting a vulnerability
+
+Please **do not open a public GitHub issue** for security reports.
+
+Email **sergey@mm.st** with:
+
+- A description of the issue and its potential impact
+- Steps to reproduce (a minimal proof-of-concept is ideal)
+- The affected version(s)
+- Any suggested mitigation or fix
+
+You will receive an acknowledgment within **72 hours**. I will work with you on a disclosure timeline — typically a fix plus a coordinated release within 14 days for confirmed vulnerabilities, longer if the issue is complex.
+
+## Scope
+
+In scope:
+
+- Vulnerabilities in the gem's middleware, parsers, storage adapters, dashboard controllers, or generators
+- Data-exposure issues (unintended persistence of prompt content, API keys, or response bodies)
+- Injection, auth-bypass, or privilege-escalation in the mounted dashboard
+
+Out of scope:
+
+- Issues in third-party dependencies (report those upstream; mention them here only if this gem's usage pattern creates the vulnerability)
+- Missing security hardening recommendations that are not vulnerabilities (open a regular issue instead)
+- Social engineering or physical attacks
+
+## Credit
+
+Reporters who follow this policy will be credited in the release notes for the fix unless they request anonymity.

data/app/controllers/llm_cost_tracker/assets_controller.rb

@@ -2,8 +2,6 @@
 
 module LlmCostTracker
   class AssetsController < ActionController::Base
-    skip_forgery_protection if respond_to?(:skip_forgery_protection)
-
     def stylesheet
       response.set_header("Cache-Control", "public, max-age=31536000, immutable")
       send_file LlmCostTracker::Assets::STYLESHEET_PATH, type: "text/css", disposition: "inline"

data/lib/llm_cost_tracker/budget.rb

@@ -23,7 +23,7 @@ module LlmCostTracker
         return unless event.cost
 
         monthly_total = if config.active_record?
-                          active_record_monthly_total
+                          active_record_monthly_total(time: event.tracked_at)
                         else
                           event.cost.total_cost
                         end
@@ -34,11 +34,11 @@ module LlmCostTracker
 
       private
 
-      def active_record_monthly_total
+      def active_record_monthly_total(time: Time.now.utc)
         require_relative "llm_api_call" unless defined?(LlmCostTracker::LlmApiCall)
         require_relative "storage/active_record_store" unless defined?(LlmCostTracker::Storage::ActiveRecordStore)
 
-        LlmCostTracker::Storage::ActiveRecordStore.monthly_total
+        LlmCostTracker::Storage::ActiveRecordStore.monthly_total(time: time)
       rescue LoadError => e
         raise Error, "ActiveRecord storage requires the active_record gem: #{e.message}"
       end
@@ -51,10 +51,20 @@ module LlmCostTracker
           last_event: last_event
         }
 
-        config.on_budget_exceeded&.call(payload)
+        if notify_exceeded?(config, monthly_total: monthly_total, last_event: last_event)
+          config.on_budget_exceeded&.call(payload)
+        end
         raise BudgetExceededError.new(**payload) if raise_on_exceeded?(config)
       end
 
+      def notify_exceeded?(config, monthly_total:, last_event:)
+        return false unless config.on_budget_exceeded
+        return true unless config.budget_exceeded_behavior == :notify
+        return true unless last_event&.cost
+
+        monthly_total - last_event.cost.total_cost < config.monthly_budget
+      end
+
       def raise_on_exceeded?(config)
         %i[raise block_requests].include?(config.budget_exceeded_behavior)
       end

data/lib/llm_cost_tracker/generators/llm_cost_tracker/add_monthly_totals_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LlmCostTracker
+  module Generators
+    class AddMonthlyTotalsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a migration to add llm_cost_tracker_monthly_totals"
+
+      def create_migration_file
+        migration_template(
+          "add_monthly_totals_to_llm_cost_tracker.rb.erb",
+          "db/migrate/add_monthly_totals_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_monthly_totals_to_llm_cost_tracker.rb.erb

@@ -0,0 +1,48 @@
+class AddMonthlyTotalsToLlmCostTracker < ActiveRecord::Migration<%= migration_version %>
+  def up
+    create_table :llm_cost_tracker_monthly_totals do |t|
+      t.date :month_start, null: false
+      t.decimal :total_cost, precision: 20, scale: 8, null: false, default: 0
+
+      t.timestamps
+    end unless table_exists?(:llm_cost_tracker_monthly_totals)
+
+    add_index :llm_cost_tracker_monthly_totals, :month_start,
+              unique: true unless index_exists?(:llm_cost_tracker_monthly_totals, :month_start)
+
+    backfill_monthly_totals
+  end
+
+  def down
+    remove_index :llm_cost_tracker_monthly_totals, :month_start if index_exists?(:llm_cost_tracker_monthly_totals, :month_start)
+    drop_table :llm_cost_tracker_monthly_totals if table_exists?(:llm_cost_tracker_monthly_totals)
+  end
+
+  private
+
+  def backfill_monthly_totals
+    return unless table_exists?(:llm_api_calls)
+
+    execute <<~SQL
+      INSERT INTO llm_cost_tracker_monthly_totals (month_start, total_cost, created_at, updated_at)
+      SELECT #{month_bucket_sql} AS month_start,
+             SUM(total_cost) AS total_cost,
+             CURRENT_TIMESTAMP,
+             CURRENT_TIMESTAMP
+      FROM llm_api_calls
+      WHERE total_cost IS NOT NULL
+      GROUP BY #{month_bucket_sql}
+    SQL
+  end
+
+  def month_bucket_sql
+    case connection.adapter_name
+    when /postgres/i
+      "DATE_TRUNC('month', tracked_at)::date"
+    when /mysql/i
+      "DATE_FORMAT(tracked_at, '%Y-%m-01')"
+    else
+      "strftime('%Y-%m-01', tracked_at)"
+    end
+  end
+end

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

@@ -23,6 +23,13 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
+    create_table :llm_cost_tracker_monthly_totals do |t|
+      t.date :month_start, null: false
+      t.decimal :total_cost, precision: 20, scale: 8, null: false, default: 0
+
+      t.timestamps
+    end
+
     add_index :llm_api_calls, :provider
     add_index :llm_api_calls, :model
     add_index :llm_api_calls, :tracked_at
@@ -31,6 +38,7 @@ class CreateLlmApiCalls < ActiveRecord::Migration<%= migration_version %>
     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_monthly_totals, :month_start, unique: true
   end
 
   private

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

@@ -8,6 +8,7 @@ class UpgradeLlmApiCallTagsToJsonb < ActiveRecord::Migration<%= migration_versio
     return if tags_jsonb?
 
     remove_index :llm_api_calls, :tags if index_exists?(:llm_api_calls, :tags)
+    say "Upgrading llm_api_calls.tags to jsonb rewrites the table on PostgreSQL. Run this migration during a maintenance window on large datasets."
 
     change_column(
       :llm_api_calls,

data/lib/llm_cost_tracker/middleware/faraday.rb

@@ -8,6 +8,8 @@ require_relative "../logging"
 module LlmCostTracker
   module Middleware
     class Faraday < ::Faraday::Middleware
+      STREAM_CAPTURE_LIMIT_BYTES = 1_048_576
+
       def initialize(app, **options)
         super(app)
         @tags = options.fetch(:tags, {})
@@ -85,15 +87,12 @@ module LlmCostTracker
       end
 
       def parse_stream(parser, request_url, request_body, response_env, stream_buffer)
-        body = stream_buffer&.string
+        body = stream_buffer&.dig(:buffer)&.string
         body = read_body(response_env.body) if body.nil? || body.empty?
 
         if body.nil? || body.empty?
-          Logging.warn(
-            "Unable to capture streaming response for #{request_url}; " \
-            "fall back to LlmCostTracker.track_stream for manual capture."
-          )
-          return nil
+          Logging.warn(capture_warning(request_url, stream_buffer))
+          return parser.parse_stream(request_url, request_body, response_env.status, [])
         end
 
         events = Parsers::SSE.parse(body)
@@ -106,12 +105,21 @@ module LlmCostTracker
         original = request_env.request.on_data
         return nil unless original
 
-        buffer = StringIO.new
+        state = { buffer: StringIO.new, bytes: 0, overflowed: false }
         request_env.request.on_data = proc do |chunk, size, env|
-          buffer << chunk.to_s
+          chunk = chunk.to_s
+          unless state[:overflowed]
+            if state[:bytes] + chunk.bytesize <= STREAM_CAPTURE_LIMIT_BYTES
+              state[:buffer] << chunk
+              state[:bytes] += chunk.bytesize
+            else
+              state[:overflowed] = true
+              state[:buffer] = nil
+            end
+          end
           original.call(chunk, size, env)
         end
-        buffer
+        state
       rescue StandardError => e
         Logging.warn("Unable to install streaming tap: #{e.class}: #{e.message}")
         nil
@@ -145,6 +153,16 @@ module LlmCostTracker
       def elapsed_ms(started_at)
         ((monotonic_time - started_at) * 1000).round
       end
+
+      def capture_warning(request_url, stream_buffer)
+        unless stream_buffer&.dig(:overflowed)
+          return "Unable to capture streaming response for #{request_url}; " \
+                 "recording usage_source=unknown. Use LlmCostTracker.track_stream for manual capture."
+        end
+
+        "Streaming response for #{request_url} exceeded #{STREAM_CAPTURE_LIMIT_BYTES} bytes; " \
+          "recording usage_source=unknown. Use LlmCostTracker.track_stream for manual capture."
+      end
     end
   end
 end

data/lib/llm_cost_tracker/monthly_total.rb

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

data/lib/llm_cost_tracker/parsers/base.rb

@@ -23,7 +23,8 @@ module LlmCostTracker
         body = request_body.to_s
         return false if body.empty?
 
-        body.include?('"stream":true') || body.include?('"stream": true') || body.include?("stream: true")
+        request = safe_json_parse(body)
+        request.is_a?(Hash) && request["stream"] == true
       end
 
       def parse_stream(_request_url, _request_body, _response_status, _events)

data/lib/llm_cost_tracker/railtie.rb

@@ -3,7 +3,10 @@
 module LlmCostTracker
   class Railtie < Rails::Railtie
     generators do
+      require_relative "generators/llm_cost_tracker/add_monthly_totals_generator"
       require_relative "generators/llm_cost_tracker/add_latency_ms_generator"
+      require_relative "generators/llm_cost_tracker/add_provider_response_id_generator"
+      require_relative "generators/llm_cost_tracker/add_streaming_generator"
       require_relative "generators/llm_cost_tracker/install_generator"
       require_relative "generators/llm_cost_tracker/prices_generator"
       require_relative "generators/llm_cost_tracker/upgrade_cost_precision_generator"

data/lib/llm_cost_tracker/storage/active_record_store.rb

@@ -4,6 +4,10 @@ module LlmCostTracker
   module Storage
     class ActiveRecordStore
       class << self
+        def reset!
+          remove_instance_variable(:@monthly_totals_enabled) if instance_variable_defined?(:@monthly_totals_enabled)
+        end
+
         def save(event)
           tags = stringify_tags(event.tags || {})
 
@@ -26,18 +30,86 @@ module LlmCostTracker
             attributes[:provider_response_id] = event.provider_response_id
           end
 
-          LlmCostTracker::LlmApiCall.create!(attributes)
+          LlmCostTracker::LlmApiCall.transaction do
+            call = LlmCostTracker::LlmApiCall.create!(attributes)
+            increment_monthly_total(event)
+            call
+          end
         end
 
         def monthly_total(time: Time.now.utc)
-          LlmCostTracker::LlmApiCall
-            .where(tracked_at: time.beginning_of_month..time)
-            .sum(:total_cost)
-            .to_f
+          if monthly_totals_enabled?
+            monthly_total_model.where(month_start: month_start_for(time)).pick(:total_cost).to_f
+          else
+            LlmCostTracker::LlmApiCall
+              .where(tracked_at: time.beginning_of_month..time)
+              .sum(:total_cost)
+              .to_f
+          end
         end
 
         private
 
+        def increment_monthly_total(event)
+          return unless monthly_totals_enabled?
+          return unless event.cost&.total_cost
+
+          monthly_total_model.upsert_all(
+            [
+              {
+                month_start: month_start_for(event.tracked_at),
+                total_cost: event.cost.total_cost
+              }
+            ],
+            on_duplicate: monthly_total_upsert_sql,
+            record_timestamps: true,
+            unique_by: monthly_total_unique_by
+          )
+        end
+
+        def monthly_totals_enabled?
+          return @monthly_totals_enabled unless @monthly_totals_enabled.nil?
+
+          @monthly_totals_enabled =
+            LlmCostTracker::LlmApiCall.connection.data_source_exists?("llm_cost_tracker_monthly_totals")
+        end
+
+        def monthly_total_model
+          require_relative "../monthly_total" unless defined?(LlmCostTracker::MonthlyTotal)
+
+          LlmCostTracker::MonthlyTotal
+        end
+
+        def month_start_for(time)
+          time.to_time.utc.beginning_of_month.to_date
+        end
+
+        def monthly_total_unique_by
+          return unless monthly_total_model.connection.supports_insert_conflict_target?
+
+          :month_start
+        end
+
+        def monthly_total_upsert_sql
+          Arel.sql(case monthly_total_model.connection.adapter_name
+                   when /mysql/i
+                     mysql_upsert_sql
+                   else
+                     "total_cost = total_cost + excluded.total_cost, updated_at = excluded.updated_at"
+                   end)
+        end
+
+        def mysql_upsert_sql
+          connection = monthly_total_model.connection
+          if connection.respond_to?(:supports_insert_raw_alias_syntax?, true) &&
+             connection.send(:supports_insert_raw_alias_syntax?)
+            values_reference = connection.quote_table_name("#{monthly_total_model.table_name}_values")
+            "total_cost = total_cost + #{values_reference}.total_cost, updated_at = #{values_reference}.updated_at"
+          else
+            "total_cost = total_cost + VALUES(total_cost), updated_at = VALUES(updated_at)"
+          end
+        end
+
         def stringify_tags(tags)
           tags.transform_keys(&:to_s).transform_values { |value| stringify_tag_value(value) }
         end

data/lib/llm_cost_tracker/stream_collector.rb

@@ -69,7 +69,7 @@ module LlmCostTracker
 
         @finished = true
         {
-          events: ValueHelpers.deep_dup(@events),
+          events: @events.dup,
           explicit_usage: ValueHelpers.deep_dup(@explicit_usage),
           model: @model,
           latency_ms: @latency_ms,

data/lib/llm_cost_tracker/tracker.rb

@@ -10,11 +10,15 @@ module LlmCostTracker
 
     class << self
       def enforce_budget!
+        return unless LlmCostTracker.configuration.enabled
+
         Budget.enforce!
       end
 
       def record(provider:, model:, input_tokens:, output_tokens:, latency_ms: nil, stream: false,
                  usage_source: nil, provider_response_id: nil, metadata: {})
+        return unless LlmCostTracker.configuration.enabled
+
         usage = EventMetadata.usage_data(input_tokens, output_tokens, metadata)
 
         cost_data = Pricing.cost_for(

data/lib/llm_cost_tracker/unknown_pricing.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require "monitor"
+
 require_relative "logging"
 
 module LlmCostTracker
   class UnknownPricing
+    MUTEX = Monitor.new
+
     class << self
       def handle!(model)
         model = normalized_model_name(model)
@@ -18,6 +22,10 @@ module LlmCostTracker
         end
       end
 
+      def reset!
+        MUTEX.synchronize { @warned_models = Set.new }
+      end
+
       private
 
       def normalized_model_name(model)
@@ -25,6 +33,12 @@ module LlmCostTracker
       end
 
       def warn_missing(model)
+        should_warn = MUTEX.synchronize do
+          @warned_models ||= Set.new
+          @warned_models.add?(model)
+        end
+        return unless should_warn
+
         Logging.warn(
           "No pricing configured for model #{model.inspect}. " \
           "Cost and budget guardrails will be skipped for this event. " \

data/lib/llm_cost_tracker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmCostTracker
-  VERSION = "0.3.1"
+  VERSION = "0.3.3"
 end

data/lib/llm_cost_tracker.rb

@@ -60,6 +60,8 @@ module LlmCostTracker
 
     def reset_configuration!
       CONFIGURATION_MUTEX.synchronize { @configuration = Configuration.new }
+      UnknownPricing.reset! if defined?(UnknownPricing)
+      Storage::ActiveRecordStore.reset! if defined?(Storage::ActiveRecordStore)
     end
 
     def enforce_budget!

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 platform: ruby
 authors:
 - Sergii Khomenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -146,6 +146,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -192,9 +220,11 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- SECURITY.md
 - app/assets/llm_cost_tracker/application.css
 - app/controllers/llm_cost_tracker/application_controller.rb
 - app/controllers/llm_cost_tracker/assets_controller.rb
@@ -248,11 +278,13 @@ files:
 - lib/llm_cost_tracker/event.rb
 - lib/llm_cost_tracker/event_metadata.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_latency_ms_generator.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/add_monthly_totals_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_provider_response_id_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_streaming_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/install_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/prices_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_latency_ms_to_llm_api_calls.rb.erb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_monthly_totals_to_llm_cost_tracker.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_provider_response_id_to_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_streaming_to_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/create_llm_api_calls.rb.erb
@@ -265,6 +297,7 @@ files:
 - lib/llm_cost_tracker/llm_api_call.rb
 - lib/llm_cost_tracker/logging.rb
 - lib/llm_cost_tracker/middleware/faraday.rb
+- lib/llm_cost_tracker/monthly_total.rb
 - lib/llm_cost_tracker/parameter_hash.rb
 - lib/llm_cost_tracker/parsed_usage.rb
 - lib/llm_cost_tracker/parsers/anthropic.rb
@@ -308,7 +341,6 @@ files:
 - lib/llm_cost_tracker/value_helpers.rb
 - lib/llm_cost_tracker/version.rb
 - lib/tasks/llm_cost_tracker.rake
-- llm_cost_tracker.gemspec
 homepage: https://github.com/sergey-homenko/llm_cost_tracker
 licenses:
 - MIT
@@ -333,7 +365,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Self-hosted LLM usage and cost tracking for Ruby and Rails

data/llm_cost_tracker.gemspec

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/llm_cost_tracker/version"
-
-Gem::Specification.new do |spec|
-  spec.name          = "llm_cost_tracker"
-  spec.version       = LlmCostTracker::VERSION
-  spec.authors       = ["Sergii Khomenko"]
-  spec.email         = ["sergey@mm.st"]
-
-  spec.summary       = "Self-hosted LLM usage and cost tracking for Ruby and Rails"
-  spec.description   = "Tracks token usage, latency, and estimated costs for OpenAI, Anthropic, " \
-                       "Google Gemini, OpenRouter, DeepSeek, and OpenAI-compatible APIs. " \
-                       "Works through Faraday middleware or explicit track/track_stream helpers, " \
-                       "with ActiveRecord storage, tag-based attribution, price sync tasks, " \
-                       "and budget guardrails."
-  spec.homepage      = "https://github.com/sergey-homenko/llm_cost_tracker"
-  spec.license       = "MIT"
-
-  spec.required_ruby_version = ">= 3.3.0"
-
-  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
-  spec.metadata["changelog_uri"]   = "#{spec.homepage}/blob/main/CHANGELOG.md"
-  spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["documentation_uri"] = "#{spec.homepage}#readme"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?("bin/", "test/", "spec/", ".git", ".github", "gemfiles/", ".rubocop", "Gemfile")
-    end
-  end
-
-  spec.require_paths = ["lib"]
-
-  spec.add_dependency "activesupport", ">= 7.1", "< 9.0"
-  spec.add_dependency "csv", "~> 3.0"
-  spec.add_dependency "faraday", ">= 2.0", "< 3.0"
-
-  spec.add_development_dependency "activerecord", ">= 7.1", "< 9.0"
-  spec.add_development_dependency "railties", ">= 7.1", "< 9.0"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "rubocop", "~> 1.0"
-  spec.add_development_dependency "sqlite3", ">= 1.4", "< 3.0"
-  spec.add_development_dependency "webmock", "~> 3.0"
-end