flight-profiler-watch

name	flight-profiler-watch
description	Display input/output args, return object and cost time of a Python method invocation in a live process. Use this to observe function behavior at runtime — see what arguments go in, what comes back, and how long it takes. This is the most frequently used diagnostic command.

flight-profiler-watch

Display the input/output args, return object and cost time of method invocation. This is the most commonly used command for understanding runtime behavior of a specific function.

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

When to Use

• You want to see what arguments a function receives and what it returns
• You need to measure how long a specific function call takes
• You want to filter calls by argument values or return values
• You need to catch only exception-throwing invocations
• You want to observe a method's behavior without modifying its source code

Usage

flight_profiler <pid> --cmd "watch module [class] method [options]" --no-color

Use -n to limit capture count so the command auto-exits.

Positional Arguments

• module — the module name as it would be imported in the target process. For example, if the target code does from myapp.utils import helper, then module is myapp.utils. PyFlightProfiler locates the module via importlib.import_module. If you're unsure of the module name, run a separate command to resolve it first: flight_profiler <pid> --cmd "module /absolute/path/to/file.py" --no-color, then use the returned module name here.
• class (optional) — class name, omit if the method is a module-level function
• method — target method name

Options

Flag	Description	Default
--expr <value>	Watch expression. Available variables: target, return_obj, *args, **kwargs (note: cost is NOT available in expr, only in filter)	args,kwargs
-x, --expand <value>	Object tree expand level (1-4, or -1 for infinity)	1
-e, --exception	Only record when method throws exception	off
-nm, --nested-method <value>	Watch nested method with depth restrict to 1	none
-r, --raw	Use __str__ (equivalent to print(obj)) instead of default JSON serialization	off
-v, --verbose	Display all nested items in target list or dict (no truncation)	off
-n, --limits <value>	Max display count, auto-stops after reaching limit	10
-f, --filter <value>	Filter expression. Available variables: target, return_obj, cost, args, kwargs	none

Choosing the Right --expr

--expr directly controls what you see in the output. Always match the user's intent to the right expression — the default args,kwargs only shows inputs, not outputs.

User intent	--expr value
See input arguments	args,kwargs (default)
See return value / output	return_obj
See both input and output	args,kwargs,return_obj
See input, output, and the object itself	target,args,kwargs,return_obj
See a specific return field	return_obj['field_name']
See the class instance (self)	target
See everything	target,args,kwargs,return_obj

When the user says "input/output", "args and return", "what goes in and comes back", or similar — always use --expr args,kwargs,return_obj, never just the default.

Output Format

Each captured invocation produces output in this format:

────────────────────────────────────────────────────────────
✓ 2026-04-19 10:33:36:520 method=__main__.compute cost=2.380133ms is_exp=False result={
  EXPR:   args,kwargs
  TYPE:   <class 'tuple'>
  VALUE:  (
            (25, 26),
            {}
          )
}

Output Fields

Field	Description
✓ / ✗	Success or exception indicator
Timestamp	When the method was called (yyyy-MM-dd HH:mm:ss:SSS)
method	Fully qualified method name: module.method or module.class.method
cost	Execution time in milliseconds (precision to microseconds)
is_exp	True if the method threw an exception, False otherwise
EXPR	The expression used to extract the displayed value
TYPE	Python type of the expression result
VALUE	The expression result, formatted as JSON (or __str__ if -r)
EXCEPTION	(only when is_exp=True) Full traceback of the exception

Examples

Watch a module-level function (default args,kwargs)

flight_profiler <pid> --cmd "watch __main__ compute -n 1" --no-color

Output:

────────────────────────────────────────────────────────────
✓ 2026-04-19 10:33:36:520 method=__main__.compute cost=2.380133ms is_exp=False result={
  EXPR:   args,kwargs
  TYPE:   <class 'tuple'>
  VALUE:  (
            (
              25,
              26
            ),
            {}
          )
}

Watch a module-level function — only return value

flight_profiler <pid> --cmd "watch __main__ compute --expr return_obj -n 1" --no-color

Output:

────────────────────────────────────────────────────────────
✓ ... method=__main__.compute cost=2.561092ms is_exp=False result={
  EXPR:   return_obj
  TYPE:   <class 'int'>
  VALUE:  89
}

Watch a function with kwargs

flight_profiler <pid> --cmd "watch __main__ fetch_data -n 1" --no-color

Output — args contains positional args, kwargs contains keyword args:

────────────────────────────────────────────────────────────
✓ ... method=__main__.fetch_data cost=0.010014ms is_exp=False result={
  EXPR:   args,kwargs
  TYPE:   <class 'tuple'>
  VALUE:  (
            (
              "SELECT *"
            ),
            {
              "limit": 5,
              "timeout": 30
            }
          )
}

Watch a class instance method

flight_profiler <pid> --cmd "watch __main__ UserService get_user -n 1" --no-color

Output — for class methods, self is automatically stripped from args:

────────────────────────────────────────────────────────────
✓ ... method=__main__.UserService.get_user cost=10.342121ms is_exp=False result={
  EXPR:   args,kwargs
  TYPE:   <class 'tuple'>
  VALUE:  (
            (
              46
            ),
            {}
          )
}

Use --expr to see target (self) and return value

flight_profiler <pid> --cmd "watch __main__ UserService get_user --expr target,return_obj -n 1" --no-color

Output — target is the class instance (self), shown with its attributes:

────────────────────────────────────────────────────────────
✓ ... method=__main__.UserService.get_user cost=10.831118ms is_exp=False result={
  EXPR:   target,return_obj
  TYPE:   <class 'tuple'>
  VALUE:  (
            UserService({}),
            {
              "active": True,
              "id": 56,
              "name": "user_56"
            }
          )
}

Use --expr to extract a specific return field

flight_profiler <pid> --cmd "watch __main__ UserService get_user --expr return_obj['name'] -n 1" --no-color

Output:

────────────────────────────────────────────────────────────
✓ ... method=__main__.UserService.get_user cost=12.423992ms is_exp=False result={
  EXPR:   return_obj['name']
  TYPE:   <class 'str'>
  VALUE:  "user_68"
}

Watch class method with expanded output

flight_profiler <pid> --cmd "watch __main__ UserService get_user --expr return_obj -x 2 -n 1" --no-color

Output:

────────────────────────────────────────────────────────────
✓ ... method=__main__.UserService.get_user cost=12.030125ms is_exp=False result={
  EXPR:   return_obj
  TYPE:   <class 'dict'>
  VALUE:  {
            "active": True,
            "id": 81,
            "name": "user_81"
          }
}

Capture exceptions with -e

flight_profiler <pid> --cmd "watch __main__ UserService delete_user -e -n 1" --no-color

Output — note ✗, is_exp=True, and the EXCEPTION field:

────────────────────────────────────────────────────────────
✗ ... method=__main__.UserService.delete_user cost=0.024080ms is_exp=True result={
  EXPR:       args,kwargs
  TYPE:       <class 'tuple'>
  VALUE:      (
                (
                  58
                ),
                {}
              )
  EXCEPTION:  Traceback (most recent call last):
                ...
                File "watch_demo_script.py", line 11, in delete_user
                  raise ValueError(f"Cannot delete user {user_id}")
              ValueError: Cannot delete user 58
}

Watch with filter — only slow calls

flight_profiler <pid> --cmd "watch __main__ compute -f cost>10 -n 3" --no-color

Watch with filter — by argument value

flight_profiler <pid> --cmd "watch __main__ compute -f args[0]>2 -n 1" --no-color

Watch nested inner function with -nm

flight_profiler <pid> --cmd "watch __main__ UserService nested_outer -nm inner_calc -n 1" --no-color

Output — method shows the full path including nested function name:

────────────────────────────────────────────────────────────
✓ ... method=__main__.UserService.nested_outer.inner_calc cost=0.071049ms is_exp=False result={
  EXPR:   args,kwargs
  TYPE:   <class 'tuple'>
  VALUE:  (
            (),
            {}
          )
}

Raw mode -r (use __str__ instead of JSON serialization)

flight_profiler <pid> --cmd "watch __main__ compute -r -n 1" --no-color

Output — VALUE uses __str__ (like print(obj)) instead of default JSON serialization:

────────────────────────────────────────────────────────────
✓ ... method=__main__.compute cost=2.539158ms is_exp=False result={
  EXPR:   args,kwargs
  TYPE:   <class 'tuple'>
  VALUE:  ((82, 83), {})
}

--expr Expression Guide

The --expr option controls what data is displayed for each invocation. It accepts any valid Python expression.

Available variables:

• target — the class instance (self) for class methods; None for module-level functions
• return_obj — the method's return value (None if exception was thrown)
• *args — positional arguments (for class methods, self is already stripped)
• **kwargs — keyword arguments

Note: cost is NOT available in --expr. Use -f filter to filter by cost.

Common patterns:

# Default: see all args and kwargs
--expr args,kwargs

# See only return value
--expr return_obj

# See args and return value together
--expr args,return_obj

# Extract a specific field from return value
--expr return_obj['key']

# Extract nested field
--expr return_obj['data']['items']

# See the class instance (self)
--expr target

# Combine target and return
--expr target,return_obj

# Use Python expressions
--expr len(args[0])
--expr type(return_obj)

-f Filter Guide

The -f option controls which invocations are displayed. Only invocations where the filter expression evaluates to True are shown.

Available variables:

• target — the class instance (or None)
• return_obj — the return value
• cost — execution time in milliseconds
• args — positional arguments tuple
• kwargs — keyword arguments dict

Common patterns:

# Filter by execution time (cost in ms)
-f cost>10
-f cost>100

# Filter by argument value
-f args[0]>100
-f args[0]=="hello"
-f args[0]["query"]=="SELECT *"

# Filter by return value
-f return_obj is not None
-f return_obj['success']==True
-f len(return_obj)>0

# Filter by kwargs
-f kwargs.get('debug')==True

# Combine conditions
-f cost>10 and args[0]>0
-f return_obj is not None and cost<5

Troubleshooting: No Output

If watch produces no output, the most likely reason is the target method is not being called during the observation window. Before concluding there's a problem:

1. Confirm the method is on the active call path — make sure the code path that invokes the target method is actually being triggered (e.g., send a request, trigger the workflow)
2. Check the module name — use the module command to verify the correct module name if unsure
3. Check for filter issues — if using -f, the filter might be too restrictive. Try without -f first
4. Check -n limits — if limits was reached in a previous watch, the method may already be unwatched

Handling Command Output

• Long output: if the output is too long to display inline, redirect it to a file for the user to review later:

  flight_profiler <pid> --cmd "watch __main__ compute -n 5" --no-color > /tmp/watch_output.txt
  

• Short output: if the output is brief (e.g., -n 1 capturing a single invocation), display the full result directly to the user so they can see the most relevant information immediately. If multiple invocations were captured, showing just one representative case is sufficient.

Handling Large Objects

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

1. Prefer minimal extraction — use --expr to extract only the fields you need, instead of the entire object:

   # Instead of serializing the entire return object:
   --expr return_obj
   # Extract only the field you care about:
   --expr return_obj['status']
   --expr return_obj['data']['id']
   --expr type(return_obj),len(return_obj)
   

2. 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

• The -f filter runs inside the target process so it can reference live objects
• The --expr option controls what gets printed; the -f option controls which invocations get printed
• cost is only available in -f filter, not in --expr
• For class methods, self is automatically stripped from args — use target to access the instance
• Use -x 2 or -x 3 to expand nested objects in the output (max 4, or -1 for infinity)
• -r (raw) uses __str__ (like print(obj)) instead of JSON serialization — useful when objects have custom __str__ or you want the native Python representation
• -v (verbose) shows all items in lists/dicts without truncation

Related Commands

• trace — shows full call tree with timing (drill into sub-calls)
• reload — hot-patch a function after editing its source file, without restarting the process. Use watch to inspect internal behavior before/after reload when you need to observe arguments, return values, or timing changes that aren't visible from normal program output
• getglobal — inspect a specific global/static field value without watching calls

Source Files

• CLI plugin: flight_profiler/plugins/watch/cli_plugin_watch.py
• Parser: flight_profiler/plugins/watch/watch_parser.py
• Server plugin: flight_profiler/plugins/watch/server_plugin_watch.py