flight-profiler-vmtool

Inspect live Python class instances at runtime. The primary use case is state inspection — find all instances of a given class and examine their current attributes — and method invocation — call methods on found instances via -e expressions. Also supports forcing a garbage collection cycle.

Prerequisites: Read the flight-profiler-attach skill first for platform requirements, installation, permissions, and connection details.

When to Use

You want to find all live instances of a specific class and inspect their current attribute values (e.g., connection status, queue size, internal flags)
You need to invoke a method on a live instance to trigger a diagnostic action (e.g., instances[0].get_stats(), instances[0].dump_state())
You want to check how many instances of a class exist (potential memory leak investigation)
You need to filter instances by attribute to find the ones in a specific state (e.g., all connections with status == "error")
You suspect objects aren't being garbage collected and want to force GC

Usage

flight_profiler <pid> --cmd "vmtool -a <action> [options]" --no-color

Options

Flag	Description	Default
`-a, --action`	Action: `forceGc` or `getInstances`	required
`-c, --class`	Class locator: `module class`	required for getInstances
`-e, --expr <value>`	Expression to evaluate on found instances. Variable is `instances` (a list).	`instances`
`-x, --expand <value>`	Object tree expand level (1-6)	`1`
`-n, --limit <value>`	Max instances to collect (-1 for unlimited)	`10`
`-r, --raw`	Use `__str__` (equivalent to `print(obj)`) instead of default JSON serialization	off
`-v, --verbose`	Display all nested items in list/dict without truncation	off

Choosing the Right `-e` Expression

-e directly controls what you see in the output. Always match the user's intent to the right expression — the default instances dumps all found objects.

User intent	`-e` value
See all instances	`instances` (default)
Count how many instances exist	`len(instances)`
Inspect a single instance in detail	`instances[0]` (combine with `-x 2`)
Filter instances by attribute	`[i for i in instances if i.attr=='val']`
Extract one field from all instances	`[i.field for i in instances]`
Check if any instance matches a condition	`any(i.status=='error' for i in instances)`
Invoke a diagnostic method on an instance	`instances[0].get_stats()`
Invoke a method on all instances	`[i.get_status() for i in instances]`

Output Format

forceGc

Returns a plain text message:

Gc execute successfully, totally 76 unreachable objects are freed.

getInstances

Returns an expression result block (same format as getglobal/watch):

  EXPR:       instances
  TYPE:       <class 'list'>
  VALUE:      [
                Connection({'host': 'queue', 'port': 5672, 'status': 'error'}),
                Connection({'host': 'cache', 'port': 6379, 'status': 'idle'}),
                Connection({'host': 'db-replica', 'port': 5433, 'status': 'active'}),
                Connection({'host': 'db-primary', 'port': 5432, 'status': 'active'})
              ]

Field	Description
`EXPR`	The expression used (default `instances`)
`TYPE`	Python type of the expression result
`VALUE`	The value, formatted as JSON (or `__str__` if `-r`)

Examples

1. Force garbage collection

flight_profiler <pid> --cmd "vmtool -a forceGc" --no-color

Gc execute successfully, totally 76 unreachable objects are freed.

2. Find all instances of a class

flight_profiler <pid> --cmd "vmtool -a getInstances -c __main__ Connection" --no-color

  EXPR:       instances
  TYPE:       <class 'list'>
  VALUE:      [
                Connection({'host': 'queue', 'port': 5672, 'status': 'error'}),
                Connection({'host': 'cache', 'port': 6379, 'status': 'idle'}),
                Connection({'host': 'db-replica', 'port': 5433, 'status': 'active'}),
                Connection({'host': 'db-primary', 'port': 5432, 'status': 'active'})
              ]

3. Count instances

flight_profiler <pid> --cmd "vmtool -a getInstances -c __main__ Connection -e len(instances)" --no-color

  EXPR:       len(instances)
  TYPE:       <class 'int'>
  VALUE:      4

4. Inspect a specific instance with expanded attributes

Use -e instances[0] to pick one instance and -x 2 to expand its attributes:

flight_profiler <pid> --cmd "vmtool -a getInstances -c __main__ Connection -e instances[0] -x 2" --no-color

  EXPR:       instances[0]
  TYPE:       <class '__main__.Connection'>
  VALUE:      Connection({
                "host": "queue",
                "port": 5672,
                "status": "error"
              })

5. Filter instances by attribute

Find only instances with status == "error". Note: list comprehension expressions with quotes need careful shell escaping:

flight_profiler <pid> --cmd 'vmtool -a getInstances -c __main__ Connection -e "[i for i in instances if i.status==\"error\"]"' --no-color

  EXPR:       [i for i in instances if i.status=="error"]
  TYPE:       <class 'list'>
  VALUE:      [
                Connection({'host': 'queue', 'port': 5672, 'status': 'error'})
              ]

6. Raw mode `-r` (use `str` instead of JSON)

flight_profiler <pid> --cmd "vmtool -a getInstances -c __main__ Connection -r" --no-color

  EXPR:       instances
  TYPE:       <class 'list'>
  VALUE:      [<__main__.Connection object at 0x1056debb0>, <__main__.Connection object at 0x1056dec10>, ...]

Shows Python's default __str__ representation for each object.

7. Limit collected instances with `-n`

-n 2 collects at most 2 instances:

flight_profiler <pid> --cmd "vmtool -a getInstances -c __main__ Connection -n 2" --no-color

  EXPR:       instances
  TYPE:       <class 'list'>
  VALUE:      [
                Connection({'host': 'queue', 'port': 5672, 'status': 'error'}),
                Connection({'host': 'cache', 'port': 6379, 'status': 'idle'})
              ]

8. Inspect instances of a different class

flight_profiler <pid> --cmd "vmtool -a getInstances -c __main__ Task -e instances[0] -x 2" --no-color

  EXPR:       instances[0]
  TYPE:       <class '__main__.Task'>
  VALUE:      Task({
                "name": "cleanup_logs",
                "priority": 1,
                "task_id": 3
              })

`-e` Expression Guide

The -e option accepts any valid Python expression. The variable instances is a list containing the found class instances.

Common patterns:

# Default: show all instances
-e instances

# Count instances
-e len(instances)

# Pick a specific instance
-e instances[0]

# Filter by attribute
-e "[i for i in instances if i.status=='error']"

# Get a specific attribute from all instances
-e "[i.host for i in instances]"

# Check if any instance matches a condition
-e "any(i.status=='error' for i in instances)"

# Aggregate values
-e "sum(i.priority for i in instances)"

# Invoke a method on an instance
-e instances[0].get_stats()
-e instances[0].health_check()

# Invoke a method on all instances
-e "[i.get_status() for i in instances]"

Note: When using list comprehensions or expressions with quotes in shell, use single quotes for the outer --cmd and escaped double quotes inside the expression (see example 5).

Note: -e expressions execute inside the target process. Invoking methods on instances will actually run them — use this for read-only diagnostic methods (e.g., get_stats(), dump_state()). Avoid calling methods with side effects unless you intend to.

Handling Command Output

Long output: if many instances are found or instance attributes are large, redirect the output to a file for the user to review later:
```
flight_profiler <pid> --cmd "vmtool -a getInstances -c __main__ Connection -n -1 -v" --no-color > /tmp/vmtool_output.txt
```
Short output: if the result is brief (e.g., a count via -e len(instances), or a few instances), display the full result directly to the user so they can see it immediately.

Handling Large Objects

When an object is too large to serialize or the output is truncated/incomplete:

Prefer minimal extraction — use -e to extract only the fields you need, instead of the entire instance:

# Instead of serializing the entire instance:
-e instances[0]
# Extract only the field you care about:
-e instances[0].status
-e [i.host for i in instances]
-e type(instances[0]),len(vars(instances[0]))

Use -v (verbose) — if you do need the full object, add -v to disable truncation so all nested items in lists/dicts are shown completely.

Tips

Use -e expressions to filter and analyze instances without dumping everything
The instances variable in -e is a list — you can use any Python list operation on it
Use -n to limit collection when you only need a sample — collecting all instances of a very common class can be slow
Instance order is determined by gc.get_referrers() — it may not match creation order

Related Commands

getglobal — inspect a known global variable (vmtool is for finding unknown instances)
console — for more complex inspection logic

Source Files

CLI plugin: flight_profiler/plugins/vmtool/cli_plugin_vmtool.py
Parser: flight_profiler/plugins/vmtool/vmtool_parser.py
Server plugin: flight_profiler/plugins/vmtool/server_plugin_vmtool.py