llm_cost_tracker 0.5.1 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc48791f2f21576da80d4a05ed149290dd309ab9d6f9af3774df56cc389224a4
-  data.tar.gz: bb9de40f1669907210da3321cb4cc85999be8d748afa39a16f9fae7bceea9378
+  metadata.gz: 9d515abad24d5659f797d5ea0426d6111dc41baf78809181128546e29ac566db
+  data.tar.gz: 90da1dda161661423f6034f28d7bb359e06c39f48b9f4872cb0eba9a123f8948
 SHA512:
-  metadata.gz: 5a8a68b4f567fbfce3158df20a1e34b6bb6a5ea4a4162b28206bbfe099c1b36288e89f8db29dcc60617da44d7d07acdf6b38d3747f4ffb683dedfc059d1f4089
-  data.tar.gz: 5f8493e21e71e9ce43ad7ac33386f1dc39a03ac0b48cc0bad71232a21b2e2ebfc3bddd5be6b2109dbdadecbad47f79fad0c40519394fbdfad74a9a5ec5aa158c
+  metadata.gz: aa7af4b5caca984cbcb4c8a7a267600251962e1879de8f3bff32d8a3f6e8d22888ba4a26036de09c36345566e3c309a2868012b66b5dcc970e52bcb6b5e444be
+  data.tar.gz: 932f2bb680690ed043eb719debddd58ac85c7f1cbbd0ec9c30c95f5595d71a5f70516b3d8d19ca65929856c4ade902a813da34b4de2053f553aa916eece66865

data/CHANGELOG.md

@@ -4,6 +4,33 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-04-27
+
+### Added
+
+- RubyLLM SDK integration for chat, embedding, and transcription calls.
+- Tag guardrails for redacted tag keys, maximum tag count, and maximum tag value byte size.
+
+### Changed
+
+- SDK integrations now validate minimum versions and method contracts before installing wrappers.
+- `config.instrument :all` now includes RubyLLM.
+- Dashboard date filters now reject one-sided, reversed, and over-366-day ranges.
+- Dashboard provider/model/tag option lists and tag value breakdowns now cap rendered rows.
+- Reports now cap rendered breakdown groups while keeping complete structured report data available.
+- Stream capture now enforces a shared 1 MiB buffer cap and records unknown usage on overflow.
+- Price refresh, price scrape, and local price registry reads now enforce response or file size caps.
+- Retention pruning now rejects non-positive batch sizes and invalid cutoffs before deleting rows.
+- The install generator now warns to mount the dashboard behind host-app admin authentication.
+
+### Fixed
+
+- OpenAI SDK integration now separates cached input tokens from regular input tokens.
+- OpenAI and Gemini parsers now compute total tokens when provider responses omit totals.
+- CSV export now prefixes formula-like values even when they have leading whitespace.
+- Tag chips now truncate oversized values and tooltips.
+- Report tag breakdown keys are validated at configuration time.
+
 ## [0.5.1] - 2026-04-27
 
 ### Changed

data/README.md

@@ -20,7 +20,7 @@ Add to your Gemfile alongside whatever LLM client you already use:
 
 ```ruby
 gem "llm_cost_tracker"
-gem "openai"  # or "anthropic", or your existing client
+gem "openai"  # or "anthropic", "ruby_llm", or your existing client
 ```
 
 Install, migrate, verify:
@@ -55,7 +55,7 @@ Visit `/llm-costs` for the dashboard. **Mount it behind your app's auth before d
 ## What you get
 
 - Local ActiveRecord ledger of every call: provider, model, token breakdown, cost, latency, tags, response IDs
-- Auto-capture for the official `openai` and `anthropic` Ruby SDKs, plus Faraday middleware for `ruby-openai`, the Gemini REST API, and any client you can inject middleware into
+- Auto-capture for RubyLLM and the official `openai` and `anthropic` Ruby SDKs, plus Faraday middleware for `ruby-openai`, the Gemini REST API, and any client you can inject middleware into
 - Server-rendered dashboard (plain ERB, zero JavaScript) with overview, models, calls, tags, CSV export, and a data-quality page
 - Local pricing snapshots refreshed daily from the official provider pricing pages, applied with `bin/rails llm_cost_tracker:prices:refresh`
 - Monthly / daily / per-call budget guardrails with notify, raise, or block-requests behaviour
@@ -73,13 +73,13 @@ Visit `/llm-costs` for the dashboard. **Mount it behind your app's auth before d
 
 Three paths, in order of preference. Use the first one that fits your stack.
 
-### 1. Official SDK integrations
+### 1. SDK integrations
 
-Drop-in for the official `openai` and `anthropic` gems. `config.instrument` patches the SDK's resource methods so you don't change a single call site:
+Drop-in for RubyLLM and the official `openai` and `anthropic` gems. `config.instrument` patches tested SDK methods so you don't change a single call site:
 
 ```ruby
 LlmCostTracker.configure do |config|
-  config.instrument :openai      # or :anthropic, or :all
+  config.instrument :openai      # or :anthropic / :ruby_llm
 end
 
 LlmCostTracker.with_tags(feature: "support_chat") do
@@ -93,7 +93,9 @@ end
 
 Captures usage, model, latency, response ID, cache tokens, and reasoning tokens whenever the SDK exposes them. Provider SDKs are not added as gem dependencies — you install whichever you actually use.
 
-This patches **only** the official Ruby SDKs. `ruby-openai` (alexrudall) and any custom client go through Faraday middleware below.
+Enabled integrations are checked at boot: the client gem must be loaded, meet the minimum supported version, and expose the expected classes and methods. If the contract check fails, boot raises instead of silently missing spend.
+
+This patches **only** RubyLLM and the official Ruby SDKs. `ruby-openai` (alexrudall) and any custom client go through Faraday middleware below.
 
 ### 2. Faraday middleware
 
@@ -227,6 +229,8 @@ Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs
 | Other OpenAI-compatible hosts | Configurable | Register the host via `config.openai_compatible_providers` |
 | Anything else | Configurable | Custom parser — see [`docs/extending.md`](docs/extending.md) |
 
+RubyLLM chat, embedding, and transcription calls are captured through RubyLLM's provider layer when `config.instrument :ruby_llm` is enabled.
+
 Endpoints covered end-to-end: OpenAI Chat Completions / Responses / Completions / Embeddings, Anthropic Messages, Gemini `generateContent` and `streamGenerateContent`, plus their OpenAI-compatible equivalents. Streaming is captured for Faraday paths whenever the provider emits final-usage events.
 
 ## Privacy
@@ -256,7 +260,7 @@ is still brief.
 ## Known limitations
 
 - `:block_requests` is best-effort under concurrency, not a transactional cap.
-- Official SDK integrations cover non-streaming calls; streaming via the SDKs falls back to Faraday middleware or `track_stream`.
+- Official OpenAI and Anthropic SDK integrations cover non-streaming calls; streaming via those SDKs falls back to Faraday middleware or `track_stream`.
 - Streaming usage capture relies on the provider emitting a final-usage event. Missing events are stored with `usage_source: "unknown"` so they appear on the data-quality page rather than vanishing.
 - `provider_response_id` is stored only when the provider exposes a stable ID. Gemini is best-effort and varies by endpoint.
 - Cache write TTL variants on Anthropic (1h vs 5min writes) are not modeled separately yet.

data/app/controllers/llm_cost_tracker/calls_controller.rb

@@ -84,7 +84,8 @@ module LlmCostTracker
       return value if value.nil?
 
       string = value.to_s
-      CSV_FORMULA_PREFIXES.include?(string[0]) ? "'#{string}" : string
+      stripped = string.lstrip
+      CSV_FORMULA_PREFIXES.include?(stripped[0]) ? "'#{string}" : string
     end
   end
 end

data/app/controllers/llm_cost_tracker/dashboard_controller.rb

@@ -3,7 +3,9 @@
 module LlmCostTracker
   class DashboardController < ApplicationController
     def index
-      @from_date, @to_date = overview_range
+      range = Dashboard::DateRange.call(params: params)
+      @from_date = range.from
+      @to_date = range.to
       prev_from, prev_to = previous_range
       filter_params = LlmCostTracker::ParameterHash.to_hash(params)
       scope = Dashboard::Filter.call(
@@ -23,25 +25,11 @@ module LlmCostTracker
 
     private
 
-    def overview_range
-      to_date = parsed_date(params[:to]) || Date.current
-      from_date = parsed_date(params[:from]) || (to_date - 29)
-      [from_date, to_date]
-    end
-
     def previous_range
       span_days = (@to_date - @from_date).to_i + 1
       prev_to = @from_date - 1
       prev_from = prev_to - (span_days - 1)
       [prev_from, prev_to]
     end
-
-    def parsed_date(value)
-      return nil if value.to_s.strip.empty?
-
-      Date.iso8601(value.to_s)
-    rescue ArgumentError
-      nil
-    end
   end
 end

data/app/controllers/llm_cost_tracker/tags_controller.rb

@@ -8,12 +8,13 @@ module LlmCostTracker
 
     def show
       @tag_key = params[:key]
-      @rows = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: @tag_key)
-      @total_calls = @rows.sum(&:calls)
-
-      tagged_rows = @rows.reject { |r| r.value == "(untagged)" }
-      @tagged_calls = tagged_rows.sum(&:calls)
-      @distinct_values = tagged_rows.size
+      breakdown = Dashboard::TagBreakdown.call(scope: Dashboard::Filter.call(params: params), key: @tag_key)
+      @rows = breakdown.rows
+      @total_calls = breakdown.total_calls
+      @tagged_calls = breakdown.tagged_calls
+      @distinct_values = breakdown.distinct_values
+      @tag_value_limit = breakdown.limit
+      @tag_values_limited = breakdown.limited?
     end
   end
 end

data/app/helpers/llm_cost_tracker/application_helper.rb

@@ -4,6 +4,9 @@ require "json"
 
 module LlmCostTracker
   module ApplicationHelper
+    TAG_VALUE_SUMMARY_BYTES = 80
+    TAG_TOOLTIP_BYTES = 512
+
     include DashboardFilterHelper
     include DashboardFilterOptionsHelper
     include DashboardQueryHelper
@@ -116,6 +119,10 @@ module LlmCostTracker
       visible
     end
 
+    def tag_chips_title(tags)
+      truncate_text(safe_json(tags), TAG_TOOLTIP_BYTES)
+    end
+
     def budget_fill_modifier(percent)
       percent = percent.to_f
       return "lct-budget-fill--over" if percent >= 100.0
@@ -143,12 +150,20 @@ module LlmCostTracker
     end
 
     def tag_value_summary(value)
-      case value
-      when Hash, Array
-        JSON.generate(value)
-      else
-        value.to_s
-      end
+      string = case value
+               when Hash, Array
+                 JSON.generate(value)
+               else
+                 value.to_s
+               end
+
+      truncate_text(string, TAG_VALUE_SUMMARY_BYTES)
+    end
+
+    def truncate_text(string, limit)
+      return string if string.bytesize <= limit
+
+      "#{string.byteslice(0, limit).to_s.encode('UTF-8', invalid: :replace, undef: :replace)}..."
     end
   end
 end

data/app/helpers/llm_cost_tracker/dashboard_filter_options_helper.rb

@@ -2,6 +2,8 @@
 
 module LlmCostTracker
   module DashboardFilterOptionsHelper
+    MAX_FILTER_OPTIONS = 100
+
     def provider_filter_options(filter_params: params)
       filter_options_for(:provider, filter_params: filter_params)
     end
@@ -19,7 +21,7 @@ module LlmCostTracker
       )
       values = LlmCostTracker::Dashboard::Filter.call(params: scope_params)
                                                 .where.not(column => [nil, ""])
-                                                .distinct.order(column).pluck(column)
+                                                .distinct.order(column).limit(MAX_FILTER_OPTIONS).pluck(column)
       current = source[column.to_s].presence || source[column].presence
       values.unshift(current) if current && !values.include?(current)
       values

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module LlmCostTracker
+  module Dashboard
+    class DateRange
+      DEFAULT_DAYS = 30
+      MAX_DAYS = 366
+
+      attr_reader :from, :to
+
+      def self.call(params:, today: Date.current)
+        new(params: params, today: today)
+      end
+
+      def self.parse(params, key)
+        value = LlmCostTracker::ParameterHash.with_indifferent_access(params)[key].to_s.strip
+        return nil if value.empty?
+
+        Date.iso8601(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def self.validate!(from:, to:)
+        return if from.nil? && to.nil?
+
+        raise InvalidFilterError, "from and to dates must be provided together" if from.nil? || to.nil?
+        raise InvalidFilterError, "from date must be on or before to date" if from > to
+        return if ((to - from).to_i + 1) <= MAX_DAYS
+
+        raise InvalidFilterError, "date range cannot exceed #{MAX_DAYS} days"
+      end
+
+      def initialize(params:, today:)
+        @to = self.class.parse(params, :to) || today
+        @from = self.class.parse(params, :from) || (@to - (DEFAULT_DAYS - 1))
+        self.class.validate!(from: @from, to: @to)
+        freeze
+      end
+    end
+  end
+end

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

@@ -31,9 +31,12 @@ module LlmCostTracker
       attr_reader :scope, :params
 
       def apply_date_filters(relation)
-        from = parse_date(:from)&.beginning_of_day
-        to = parse_date(:to)&.end_of_day
+        from_date = parse_date(:from)
+        to_date = parse_date(:to)
+        Dashboard::DateRange.validate!(from: from_date, to: to_date)
 
+        from = from_date&.beginning_of_day
+        to = to_date&.end_of_day
         relation = relation.where(tracked_at: from..) if from
         relation = relation.where(tracked_at: ..to) if to
         relation
@@ -89,12 +92,7 @@ module LlmCostTracker
       end
 
       def parse_date(key)
-        value = normalized_string(params[key])
-        return nil if value.nil?
-
-        Date.iso8601(value)
-      rescue ArgumentError
-        nil
+        Dashboard::DateRange.parse(params, key)
       end
 
       def normalized_string(value)

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

@@ -65,11 +65,12 @@ module LlmCostTracker
 
         scope
           .where(tracked_at: window)
-          .pluck(:provider, :model, :tracked_at, :total_cost)
-          .each do |provider, model, tracked_at, total_cost|
-            next if total_cost.nil?
-
-            grouped[[provider, model]][tracked_at.to_date] += total_cost.to_f
+          .where.not(total_cost: nil)
+          .group(:provider, :model)
+          .group_by_period(:day)
+          .sum(:total_cost)
+          .each do |(provider, model, day), total_cost|
+            grouped[[provider, model]][Date.iso8601(day.to_s)] += total_cost.to_f
           end
 
         grouped

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

@@ -9,28 +9,54 @@ module LlmCostTracker
       :average_cost_per_call
     )
 
+    TagBreakdownResult = Data.define(
+      :rows,
+      :total_calls,
+      :tagged_calls,
+      :distinct_values,
+      :limit
+    ) do
+      def limited? = distinct_values > rows.size
+    end
+
     class TagBreakdown
+      DEFAULT_LIMIT = 100
+
       class << self
-        def call(key:, scope: LlmCostTracker::LlmApiCall.all)
-          new(scope: scope, key: key).rows
+        def call(key:, scope: LlmCostTracker::LlmApiCall.all, limit: DEFAULT_LIMIT)
+          new(scope: scope, key: key, limit: limit).result
         end
       end
 
-      def initialize(scope:, key:)
+      def initialize(scope:, key:, limit:)
         @scope = scope
         @key = LlmCostTracker::TagKey.validate!(key, error_class: LlmCostTracker::InvalidFilterError)
+        @limit = normalized_limit(limit)
+        @connection = LlmCostTracker::LlmApiCall.connection
       end
 
-      def rows
-        costs = scope.cost_by_tag(key)
-        counts = counts_by_tag
+      def result
+        counts = summary_counts
 
-        costs.map do |value, total_cost|
-          calls = counts[value].to_i
-          total_cost = total_cost.to_f
+        TagBreakdownResult.new(
+          rows: rows,
+          total_calls: counts.fetch(:total_calls),
+          tagged_calls: counts.fetch(:tagged_calls),
+          distinct_values: counts.fetch(:distinct_values),
+          limit: limit
+        )
+      end
 
+      private
+
+      attr_reader :scope, :key, :limit, :connection
+
+      def rows
+        connection.select_all(rows_sql).map do |row|
+          calls = row["calls_count"].to_i
+          total_cost = row["total_cost_sum"].to_f
           TagBreakdownRow.new(
-            value: value,
+            value: LlmCostTracker::LlmApiCall.tag_value_label(row["tag_value"]),
             calls: calls,
             total_cost: total_cost,
             average_cost_per_call: calls.positive? ? total_cost / calls : 0.0
@@ -38,18 +64,48 @@ module LlmCostTracker
         end
       end
 
-      private
+      def summary_counts
+        row = connection.select_one(summary_sql) || {}
+        {
+          total_calls: row["total_calls"].to_i,
+          tagged_calls: row["tagged_calls"].to_i,
+          distinct_values: row["distinct_values"].to_i
+        }
+      end
 
-      attr_reader :scope, :key
+      def rows_sql
+        <<~SQL.squish
+          SELECT #{tag_expression} AS tag_value,
+                 COUNT(*) AS calls_count,
+                 COALESCE(SUM(sub.total_cost), 0) AS total_cost_sum
+          FROM (#{scope.to_sql}) AS sub
+          WHERE #{tag_present_predicate}
+          GROUP BY #{tag_expression}
+          ORDER BY total_cost_sum DESC, calls_count DESC, tag_value ASC
+          LIMIT #{limit}
+        SQL
+      end
 
-      def counts_by_tag
-        scope.group_by_tag(key).count.each_with_object(Hash.new(0)) do |(raw, count), hash|
-          hash[label(raw)] += count.to_i
-        end
+      def summary_sql
+        <<~SQL.squish
+          SELECT COUNT(*) AS total_calls,
+                 COALESCE(SUM(CASE WHEN #{tag_present_predicate} THEN 1 ELSE 0 END), 0) AS tagged_calls,
+                 COUNT(DISTINCT CASE WHEN #{tag_present_predicate} THEN #{tag_expression} END) AS distinct_values
+          FROM (#{scope.to_sql}) AS sub
+        SQL
+      end
+
+      def tag_present_predicate
+        "#{tag_expression} IS NOT NULL AND #{tag_expression} != ''"
+      end
+
+      def tag_expression
+        @tag_expression ||= LlmCostTracker::LlmApiCall.tag_value_expression(key, table_name: "sub")
       end
 
-      def label(value)
-        value.nil? || value == "" ? "(untagged)" : value.to_s
+      def normalized_limit(value)
+        value = value.to_i
+        value.positive? ? [value, DEFAULT_LIMIT].min : DEFAULT_LIMIT
       end
     end
   end

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

@@ -5,15 +5,18 @@ module LlmCostTracker
     TagKeyRow = Data.define(:key, :calls_count, :distinct_values)
 
     class TagKeyExplorer
+      DEFAULT_LIMIT = 100
+
       class << self
-        def call(scope: LlmCostTracker::LlmApiCall.all)
-          new(scope: scope).rows
+        def call(scope: LlmCostTracker::LlmApiCall.all, limit: DEFAULT_LIMIT)
+          new(scope: scope, limit: limit).rows
         end
       end
 
-      def initialize(scope:)
+      def initialize(scope:, limit:)
         @scope = scope
         @connection = LlmCostTracker::LlmApiCall.connection
+        @limit = normalized_limit(limit)
       end
 
       def rows
@@ -32,7 +35,7 @@ module LlmCostTracker
 
       private
 
-      attr_reader :scope, :connection
+      attr_reader :scope, :connection, :limit
 
       def subquery
         scope.to_sql
@@ -62,6 +65,7 @@ module LlmCostTracker
             AND sub.tags != ''
           GROUP BY jt.key
           ORDER BY calls_count DESC
+          LIMIT #{limit}
         SQL
       end
 
@@ -76,6 +80,7 @@ module LlmCostTracker
             AND sub.tags::jsonb <> '{}'::jsonb
           GROUP BY key
           ORDER BY calls_count DESC
+          LIMIT #{limit}
         SQL
       end
 
@@ -91,8 +96,14 @@ module LlmCostTracker
             AND sub.tags != ''
           GROUP BY je.key
           ORDER BY calls_count DESC
+          LIMIT #{limit}
         SQL
       end
+
+      def normalized_limit(value)
+        value = value.to_i
+        value.positive? ? [value, DEFAULT_LIMIT].min : DEFAULT_LIMIT
+      end
     end
   end
 end

data/app/views/llm_cost_tracker/shared/_tag_chips.html.erb

@@ -2,7 +2,7 @@
 <% if entries.empty? %>
   <span class="lct-tag-empty">(untagged)</span>
 <% else %>
-  <span class="lct-tag-chips" title="<%= safe_json(tags) %>">
+  <span class="lct-tag-chips" title="<%= tag_chips_title(tags) %>">
     <% entries.each do |entry| %>
       <% if entry[:more] %>
         <span class="lct-tag-chip lct-tag-chip-more">+<%= entry[:more] %></span>

data/app/views/llm_cost_tracker/tags/show.html.erb

@@ -50,6 +50,10 @@
     <span><strong><%= percent(coverage_percent(@tagged_calls, @total_calls)) %></strong> coverage</span>
     <span><strong><%= number(@distinct_values) %></strong> distinct values</span>
   </p>
+
+  <% if @tag_values_limited %>
+    <p class="lct-toolbar-note">Showing top <%= number(@tag_value_limit) %> values by spend.</p>
+  <% end %>
 </section>
 
 <% if @rows.empty? %>

data/lib/llm_cost_tracker/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "tag_key"
 require_relative "value_helpers"
 require_relative "configuration/instrumentation"
 
@@ -8,31 +9,21 @@ module LlmCostTracker
   class Configuration
     include ConfigurationInstrumentation
 
-    OPENAI_COMPATIBLE_PROVIDERS = {
-      "openrouter.ai" => "openrouter",
-      "api.deepseek.com" => "deepseek"
-    }.freeze
+    OPENAI_COMPATIBLE_PROVIDERS = { "openrouter.ai" => "openrouter", "api.deepseek.com" => "deepseek" }.freeze
 
     BUDGET_EXCEEDED_BEHAVIORS = %i[notify raise block_requests].freeze
     STORAGE_ERROR_BEHAVIORS = %i[ignore warn raise].freeze
     STORAGE_BACKENDS = %i[log active_record custom].freeze
     UNKNOWN_PRICING_BEHAVIORS = %i[ignore warn raise].freeze
-    SHARED_SCALAR_ATTRIBUTES = %i[
-      enabled
-      custom_storage
-      on_budget_exceeded
-      monthly_budget
-      daily_budget
-      per_call_budget
-      log_level
-      prices_file
-    ].freeze
+    SHARED_SCALAR_ATTRIBUTES = %i[enabled custom_storage on_budget_exceeded monthly_budget daily_budget per_call_budget
+                                  log_level prices_file max_tag_count max_tag_value_bytesize].freeze
     SHARED_ENUM_ATTRIBUTES = {
       storage_backend: [STORAGE_BACKENDS, :log],
       budget_exceeded_behavior: [BUDGET_EXCEEDED_BEHAVIORS, :notify],
       storage_error_behavior: [STORAGE_ERROR_BEHAVIORS, :warn],
       unknown_pricing_behavior: [UNKNOWN_PRICING_BEHAVIORS, :warn]
     }.freeze
+    DEFAULT_REDACTED_TAG_KEYS = %w[api_key access_token authorization credential password refresh_token secret].freeze
 
     attr_reader(
       *SHARED_SCALAR_ATTRIBUTES,
@@ -41,6 +32,7 @@ module LlmCostTracker
       :pricing_overrides,
       :instrumented_integrations,
       :report_tag_breakdowns,
+      :redacted_tag_keys,
       :storage_backend,
       :storage_error_behavior,
       :unknown_pricing_behavior,
@@ -61,9 +53,12 @@ module LlmCostTracker
       self.unknown_pricing_behavior = :warn
       @log_level          = :info
       @prices_file        = nil
-      @pricing_overrides  = {}
+      @max_tag_count      = 50
+      @max_tag_value_bytesize = 1024
+      @pricing_overrides = {}
       @instrumented_integrations = []
       @report_tag_breakdowns = []
+      @redacted_tag_keys = DEFAULT_REDACTED_TAG_KEYS.dup
       self.openai_compatible_providers = OPENAI_COMPATIBLE_PROVIDERS
       @finalized = false
     end
@@ -85,7 +80,12 @@ module LlmCostTracker
 
     def report_tag_breakdowns=(value)
       ensure_shared_configuration_mutable!
-      @report_tag_breakdowns = value
+      @report_tag_breakdowns = normalize_report_tag_breakdowns(value)
+    end
+
+    def redacted_tag_keys=(value)
+      ensure_shared_configuration_mutable!
+      @redacted_tag_keys = Array(value).map(&:to_s)
     end
 
     SHARED_SCALAR_ATTRIBUTES.each do |name|
@@ -107,6 +107,7 @@ module LlmCostTracker
       @pricing_overrides = ValueHelpers.deep_freeze(@pricing_overrides || {})
       @instrumented_integrations = ValueHelpers.deep_freeze(@instrumented_integrations || [])
       @report_tag_breakdowns = ValueHelpers.deep_freeze(Array(@report_tag_breakdowns))
+      @redacted_tag_keys = ValueHelpers.deep_freeze(Array(@redacted_tag_keys))
       @openai_compatible_providers = ValueHelpers.deep_freeze(@openai_compatible_providers || {})
       @finalized = true
       self
@@ -123,6 +124,7 @@ module LlmCostTracker
         ValueHelpers.deep_dup(@instrumented_integrations || [])
       )
       copy.instance_variable_set(:@report_tag_breakdowns, ValueHelpers.deep_dup(@report_tag_breakdowns || []))
+      copy.instance_variable_set(:@redacted_tag_keys, ValueHelpers.deep_dup(@redacted_tag_keys || []))
       copy.instance_variable_set(
         :@openai_compatible_providers,
         ValueHelpers.deep_dup(@openai_compatible_providers || {})
@@ -149,6 +151,10 @@ module LlmCostTracker
       end
     end
 
+    def normalize_report_tag_breakdowns(value)
+      Array(value).map { |key| TagKey.validate!(key, error_class: Error) }
+    end
+
     def ensure_shared_configuration_mutable!
       return unless finalized?
 

data/lib/llm_cost_tracker/generators/llm_cost_tracker/install_generator.rb

@@ -39,6 +39,7 @@ module LlmCostTracker
 
         add_engine_require
         route %(mount LlmCostTracker::Engine => "/llm-costs")
+        say "Mount /llm-costs behind your app's admin auth before deploying.", :yellow
       end
 
       private