Class: Pvectl::Commands::Top::Command

Inherits:
Object
  • Object
show all
Defined in:
lib/pvectl/commands/top/command.rb,
sig/pvectl/commands/top/command.rbs

Overview

Dispatcher for the pvectl top <resource_type> command.

Displays resource usage metrics (CPU, memory, disk, swap) for cluster resources. Supports nodes, VMs, and containers.

Uses Top::ResourceRegistry for handler lookup and Top-specific presenters for metrics-focused display. VMs and containers are filtered to running-only by default (use --all to show all).

Examples:

Basic usage

Commands::Top::Command.execute("nodes", options, global_options)

Constant Summary collapse

SHOW_ALL_RESOURCE_TYPES =

Resource types where running-only filtering does NOT apply.

Returns:

%w[nodes node].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(resource_type, options, global_options, handler: nil, registry: Top::ResourceRegistry) ⇒ Command

Creates a new Top command instance.

Parameters:

  • type of resource

  • command options

  • global CLI options

  • (defaults to: nil)

    override handler for testing

  • (defaults to: Top::ResourceRegistry)

    resource registry (default: Top::ResourceRegistry)

  • (defaults to: nil)
  • (defaults to: Top::ResourceRegistry) 


99
100
101
102
103
104
105
106
 
# File 'lib/pvectl/commands/top/command.rb', line 99

def initialize(resource_type, options, global_options,
               handler: nil, registry: Top::ResourceRegistry)
  @resource_type = resource_type
  @options = options
  @global_options = global_options
  @handler = handler
  @registry = registry
end

Class Method Details

.execute(resource_type, options, global_options) ⇒ Integer

Executes the top command.

Parameters:

  • type of resource (e.g., "nodes")

  • command-specific options

    • :"sort-by" [String] sort field (cpu, memory, disk)

  • global CLI options

    • :output [String] output format (table, json, yaml, wide)
    • :color [Boolean, nil] explicit color setting

Returns:

  • exit code



88
89
90
 
# File 'lib/pvectl/commands/top/command.rb', line 88

def self.execute(resource_type, options, global_options)
  new(resource_type, options, global_options).execute
end

.register(cli) ⇒ void

This method returns an undefined value.

Registers the top command with the CLI.

Parameters:

  • the CLI application object



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/pvectl/commands/top/command.rb', line 26

def self.register(cli)
  cli.desc "Display resource usage metrics (CPU, memory, disk)"
  cli.long_desc "    Display real-time resource usage metrics for cluster resources.\n    Shows CPU, memory, disk, and network utilization in a table format.\n\n    By default, only running VMs and containers are shown. Use --all to\n    include stopped resources. Nodes always show all (including offline).\n\n    RESOURCE TYPES\n      nodes                     Cluster node metrics\n      vms                       Virtual machine metrics (running only by default)\n      containers                Container metrics (running only by default)\n\n    EXAMPLES\n      Cluster node resource usage:\n        $ pvectl top nodes\n\n      VMs sorted by CPU usage:\n        $ pvectl top vms --sort-by cpu\n\n      All containers including stopped:\n        $ pvectl top containers --all\n\n      Memory usage in JSON format:\n        $ pvectl top vms --sort-by memory -o json\n\n    NOTES\n      Sort fields: cpu, memory, disk, netin, netout, name, node.\n\n      Stopped VMs/containers show 0% for all metrics. Use --all\n      if you need to see them alongside running resources.\n\n    SEE ALSO\n      pvectl help get           List resources with status info\n      pvectl help describe      Detailed resource information\n  HELP\n  cli.arg_name \"RESOURCE_TYPE\"\n  cli.command :top do |c|\n    c.desc \"Sort by field (cpu, memory, disk, netin, netout, name, node)\"\n    c.flag [:\"sort-by\"], arg_name: \"FIELD\"\n\n    c.desc \"Show all (including stopped)\"\n    c.switch [:all], default_value: false\n\n    c.action do |global_options, options, args|\n      resource_type = args[0]\n      exit_code = execute(resource_type, options, global_options)\n      exit exit_code if exit_code != 0\n    end\n  end\nend\n"

Instance Method Details

#determine_color_enabled ⇒ Boolean

Determines if color output should be enabled.

Returns:

  • true if color should be enabled



197
198
199
200
201
202
 
# File 'lib/pvectl/commands/top/command.rb', line 197

def determine_color_enabled
  explicit = @global_options[:color]
  return explicit unless explicit.nil?

  $stdout.tty?
end

#execute ⇒ Integer

Executes the top operation.

Returns:

  • exit code



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/pvectl/commands/top/command.rb', line 111

def execute
  return missing_resource_type_error if @resource_type.nil?

  handler = @handler || @registry.for(@resource_type)
  return unknown_resource_error unless handler

  models = handler.list(sort: @options[:"sort-by"])
  models = filter_running(models) unless @options[:all]
  output = format_output(models, handler.presenter)
  puts output

  ExitCodes::SUCCESS
rescue Pvectl::Config::ConfigNotFoundError,
       Pvectl::Config::InvalidConfigError,
       Pvectl::Config::ContextNotFoundError,
       Pvectl::Config::ClusterNotFoundError,
       Pvectl::Config::UserNotFoundError => e
  $stderr.puts "Error: #{e.message}"
  ExitCodes::CONFIG_ERROR
rescue Timeout::Error => e
  output_connection_error(e.message)
  ExitCodes::CONNECTION_ERROR
rescue Errno::ECONNREFUSED => e
  output_connection_error(e.message)
  ExitCodes::CONNECTION_ERROR
rescue SocketError => e
  output_connection_error(e.message)
  ExitCodes::CONNECTION_ERROR
end

#filter_running(models) ⇒ Array<Object>

Filters models to running-only for VM/CT resource types. Nodes always show all (offline nodes are important info).

Parameters:

  • models to filter

Returns:

  • filtered models



167
168
169
170
171
172
 
# File 'lib/pvectl/commands/top/command.rb', line 167

def filter_running(models)
  return models if SHOW_ALL_RESOURCE_TYPES.include?(@resource_type)
  return models unless models.first.respond_to?(:running?)

  models.select(&:running?)
end

#format_output(models, presenter) ⇒ String

Formats models for output using the appropriate formatter.

Parameters:

  • collection of models

  • presenter for the resource type

Returns:

  • formatted output



187
188
189
190
191
192
 
# File 'lib/pvectl/commands/top/command.rb', line 187

def format_output(models, presenter)
  format = @global_options[:output] || "table"
  color_enabled = determine_color_enabled
  formatter = Formatters::Registry.for(format)
  formatter.format(models, presenter, color_enabled: color_enabled)
end

#missing_resource_type_error ⇒ Integer

Outputs error for missing resource type argument.

Returns:

  • USAGE_ERROR exit code



146
147
148
149
150
151
 
# File 'lib/pvectl/commands/top/command.rb', line 146

def missing_resource_type_error
  $stderr.puts "Error: resource type is required"
  $stderr.puts "Usage: pvectl top RESOURCE_TYPE [options]"
  $stderr.puts "Available resources: nodes, vms, containers"
  ExitCodes::USAGE_ERROR
end

#output_connection_error(message) ⇒ void

This method returns an undefined value.

Outputs connection error message.

Parameters:

  • the error message



178
179
180
 
# File 'lib/pvectl/commands/top/command.rb', line 178

def output_connection_error(message)
  $stderr.puts "Error: #{message}"
end

#unknown_resource_error ⇒ Integer

Outputs error for unknown resource type.

Returns:

  • USAGE_ERROR exit code



156
157
158
159
160
 
# File 'lib/pvectl/commands/top/command.rb', line 156

def unknown_resource_error
  $stderr.puts "Unknown resource type: #{@resource_type}"
  $stderr.puts "Available resources: nodes, vms, containers"
  ExitCodes::USAGE_ERROR
end