Snakepit.Diagnostics.ProfileInspector (Snakepit v0.6.10)

View Source

Programmatic inspection of pool profiles and worker statistics.

This module provides functions to analyze pool configurations, worker profiles, capacity utilization, memory usage, and performance metrics for both process and thread profile workers.

Features

  • Pool configuration inspection
  • Worker profile analysis (process vs thread)
  • Capacity utilization metrics
  • Memory usage per worker
  • Thread usage for thread profile pools
  • Memory-threshold recycle counters per pool
  • Performance statistics

Examples

# Get statistics for a specific pool
{:ok, stats} = ProfileInspector.get_pool_stats(:default)

# Analyze capacity utilization
{:ok, capacity} = ProfileInspector.get_capacity_stats(:hpc_pool)

# Get memory usage breakdown
{:ok, memory} = ProfileInspector.get_memory_stats(:default)

# Get comprehensive report for all pools
{:ok, report} = ProfileInspector.get_comprehensive_report()

Summary

Types

capacity_stats()
memory_stats()
pool_name()
pool_stats()
thread_info()
worker_stats()

Functions

check_saturation(pool_name \\ :default, threshold \\ 80.0)

Check if a pool is approaching capacity saturation.

get_capacity_stats(pool_name \\ :default)

Get capacity statistics for a pool.

get_comprehensive_report()

Get comprehensive report for all configured pools.

get_memory_stats(pool_name \\ :default)

Get memory statistics for a pool.

get_pool_stats(pool_name \\ :default)

Get comprehensive statistics for a specific pool.

get_recommendations(pool_name \\ :default)

Get recommendations for pool configuration based on current usage.

Types

capacity_stats()

@type capacity_stats() :: %{
  total_capacity: non_neg_integer(),
  used_capacity: non_neg_integer(),
  available_capacity: non_neg_integer(),
  utilization_percent: float(),
  thread_info: thread_info() | nil
}

memory_stats()

@type memory_stats() :: %{
  total_memory_mb: float(),
  avg_memory_per_worker_mb: float(),
  max_memory_worker_mb: float(),
  min_memory_worker_mb: float(),
  workers: [{String.t(), float()}]
}

pool_name()

@type pool_name() :: atom()

pool_stats()

@type pool_stats() :: %{
  pool_name: pool_name(),
  profile: :process | :thread,
  worker_count: non_neg_integer(),
  capacity_total: non_neg_integer(),
  capacity_used: non_neg_integer(),
  capacity_available: non_neg_integer(),
  utilization_percent: float(),
  memory_recycles: non_neg_integer(),
  workers: [worker_stats()]
}

thread_info()

@type thread_info() :: %{
  workers: non_neg_integer(),
  threads_per_worker: pos_integer(),
  total_threads: non_neg_integer(),
  avg_load_per_worker: float()
}

worker_stats()

@type worker_stats() :: %{
  worker_id: String.t(),
  pid: pid(),
  profile: :process | :thread,
  capacity: pos_integer(),
  load: non_neg_integer(),
  memory_mb: float(),
  status: :available | :busy | :unknown
}

Functions

check_saturation(pool_name \\ :default, threshold \\ 80.0)

@spec check_saturation(pool_name(), float()) ::
  {:ok, :healthy}
  | {:warning, :approaching_saturation, float()}
  | {:error, term()}

Check if a pool is approaching capacity saturation.

Returns a warning if utilization is above the threshold (default 80%).

Examples

iex> ProfileInspector.check_saturation(:default)
{:ok, :healthy}

iex> ProfileInspector.check_saturation(:busy_pool)
{:warning, :approaching_saturation, 85.5}

get_capacity_stats(pool_name \\ :default)

@spec get_capacity_stats(pool_name()) :: {:ok, capacity_stats()} | {:error, term()}

Get capacity statistics for a pool.

Returns information about total capacity, utilization, and thread-specific metrics for thread profile pools.

Examples

iex> ProfileInspector.get_capacity_stats(:hpc_pool)
{:ok, %{
  total_capacity: 64,
  used_capacity: 42,
  available_capacity: 22,
  utilization_percent: 65.6,
  thread_info: %{
    workers: 4,
    threads_per_worker: 16,
    total_threads: 64,
    avg_load_per_worker: 10.5
  }
}}

get_comprehensive_report()

@spec get_comprehensive_report() ::
  {:ok, %{required(pool_name()) => pool_stats()}} | {:error, term()}

Get comprehensive report for all configured pools.

Returns a map of pool names to their statistics.

Examples

iex> ProfileInspector.get_comprehensive_report()
{:ok, %{
  default: %{...},
  hpc_pool: %{...}
}}

get_memory_stats(pool_name \\ :default)

@spec get_memory_stats(pool_name()) :: {:ok, memory_stats()} | {:error, term()}

Get memory statistics for a pool.

Returns aggregate and per-worker memory usage statistics.

Examples

iex> ProfileInspector.get_memory_stats(:default)
{:ok, %{
  total_memory_mb: 2048.5,
  avg_memory_per_worker_mb: 20.5,
  max_memory_worker_mb: 45.2,
  min_memory_worker_mb: 15.8,
  workers: [{"worker_1", 20.5}, ...]
}}

get_pool_stats(pool_name \\ :default)

@spec get_pool_stats(pool_name()) :: {:ok, pool_stats()} | {:error, term()}

Get comprehensive statistics for a specific pool.

Returns detailed information about the pool's configuration, workers, capacity utilization, and performance metrics.

Examples

iex> ProfileInspector.get_pool_stats(:default)
{:ok, %{
  pool_name: :default,
  profile: :process,
  worker_count: 100,
  capacity_total: 100,
  capacity_used: 45,
  capacity_available: 55,
  utilization_percent: 45.0,
  workers: [...]
}}

get_recommendations(pool_name \\ :default)

@spec get_recommendations(pool_name()) :: {:ok, [String.t()]} | {:error, term()}

Get recommendations for pool configuration based on current usage.

Analyzes current pool statistics and provides recommendations for optimization.

Examples

iex> ProfileInspector.get_recommendations(:default)
{:ok, [
  "Pool utilization is high (85%). Consider adding more workers.",
  "Average memory per worker is 45MB. Monitor for memory leaks."
]}