ExLLM.Testing.TestCacheStats (ex_llm v0.8.1)

View Source

Track cache performance and cost savings with timestamp-based metrics.

This module provides comprehensive statistics tracking for the automatic test response caching system, including hit/miss ratios, cost savings, performance improvements, and storage optimization metrics.

Summary

Functions

Returns a specification to start this module under a supervisor.

Format duration in milliseconds.

Format a percentage value.

Get cache age statistics.

Get detailed statistics for a specific cache key.

Get cache efficiency metrics for monitoring.

Get comprehensive cache statistics for all cache keys.

Get statistics for a specific provider.

Get refresh reasons statistics.

Get basic cache statistics.

Get cache statistics by provider.

Get cache statistics by test suite/module.

Get storage statistics.

Get test-specific statistics.

Print a formatted cache summary to the console.

Print cache statistics by provider.

Record a cost saving event.

Record cost savings from cache usage.

Record fallback usage.

Record a cache hit event.

Record a cache miss event.

Record a cache operation for statistics.

Record a refresh event.

Record storage usage metrics.

Record time saved by using cache.

Reset all cache statistics.

Types

cache_stats()

@type cache_stats() :: %{
  total_requests: non_neg_integer(),
  cache_hits: non_neg_integer(),
  cache_misses: non_neg_integer(),
  hit_rate: float(),
  ttl_refreshes: non_neg_integer(),
  fallback_uses: non_neg_integer(),
  expired_cache_uses: non_neg_integer(),
  total_response_time_ms: non_neg_integer(),
  cached_response_time_ms: non_neg_integer(),
  real_response_time_ms: non_neg_integer(),
  time_savings_ms: non_neg_integer(),
  estimated_cost_savings: float(),
  real_api_calls_saved: non_neg_integer(),
  total_cache_size: non_neg_integer(),
  unique_content_size: non_neg_integer(),
  deduplication_savings: non_neg_integer(),
  timestamp_count: non_neg_integer(),
  oldest_cache_entry: DateTime.t() | nil,
  newest_cache_entry: DateTime.t() | nil,
  average_cache_age_days: float()
}

provider_stats()

@type provider_stats() :: %{provider: atom(), stats: cache_stats()}

test_suite_stats()

@type test_suite_stats() :: %{test_module: String.t(), stats: cache_stats()}

Functions

child_spec(arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

format_duration(ms)

@spec format_duration(number()) :: String.t()

Format duration in milliseconds.

format_percentage(ratio)

@spec format_percentage(float()) :: String.t()

Format a percentage value.

get_cache_age_stats()

@spec get_cache_age_stats() :: map()

Get cache age statistics.

get_cache_key_stats(cache_key)

@spec get_cache_key_stats(String.t()) :: cache_stats()

Get detailed statistics for a specific cache key.

get_efficiency_metrics()

@spec get_efficiency_metrics() :: map()

Get cache efficiency metrics for monitoring.

get_global_stats()

@spec get_global_stats() :: cache_stats()

Get comprehensive cache statistics for all cache keys.

get_provider_stats(provider)

@spec get_provider_stats(atom() | String.t()) :: map()

Get statistics for a specific provider.

get_refresh_reasons()

@spec get_refresh_reasons() :: map()

Get refresh reasons statistics.

get_stats()

@spec get_stats() :: map()

Get basic cache statistics.

get_stats_by_provider()

@spec get_stats_by_provider() :: [provider_stats()]

Get cache statistics by provider.

get_stats_by_test_suite()

@spec get_stats_by_test_suite() :: [test_suite_stats()]

Get cache statistics by test suite/module.

get_storage_stats()

@spec get_storage_stats() :: map()

Get storage statistics.

get_test_stats(test_key)

@spec get_test_stats(String.t()) :: map()

Get test-specific statistics.

record_cost_saving(provider, amount)

@spec record_cost_saving(String.t(), float()) :: :ok

Record a cost saving event.

record_cost_savings(metrics)

@spec record_cost_savings(map() | float()) :: :ok

Record cost savings from cache usage.

record_fallback(metadata)

@spec record_fallback(map()) :: :ok

Record fallback usage.

record_hit(metadata)

@spec record_hit(map()) :: :ok

Record a cache hit event.

record_miss(metadata)

@spec record_miss(map()) :: :ok

Record a cache miss event.

record_operation(cache_key, operation, metadata \\ %{})

@spec record_operation(String.t(), atom(), map()) :: :ok

Record a cache operation for statistics.

record_refresh(metadata)

@spec record_refresh(map()) :: :ok

Record a refresh event.

record_storage_usage(metrics)

@spec record_storage_usage(map()) :: :ok

Record storage usage metrics.

record_time_saved(ms)

@spec record_time_saved(non_neg_integer()) :: :ok

Record time saved by using cache.

reset_stats()

@spec reset_stats() :: :ok

Reset all cache statistics.

Clears all in-memory statistics. Note that this doesn't affect the actual cache files, only the statistics tracking.

start_link(opts \\ [])