// Trace execution time of Python method invocations in a live process with call stack visualization. Use this to see a hierarchical call tree showing which sub-calls are slow and where time is spent within a function.
Prerequisites and connection details for attaching to a live Python process with PyFlightProfiler. Read this skill first before using any other PyFlightProfiler command (watch, trace, stack, perf, etc.).
Inspect Python module global field or class static field value in a running Python process. Use this for safe, read-only inspection of global variables, configuration objects, or class-level state.
Translate a file path to its Python module name in a running Python process. Use this when you know a file path but need the module name for commands like watch, trace, or reload.
Hot-reload a Python function implementation from the latest file content without restarting the process. Use this to apply code fixes live after identifying a bug with watch/trace.
Inspect stack frames of a running Python process including thread stacks, native C-level frames, and async coroutine stacks. Use this to see what each thread is currently doing and diagnose hangs, deadlocks, or stuck async tasks.
Inspect live Python class instances in a running process — find all instances of a class, examine their attributes/state, or invoke methods on them. Also supports forcing GC. Use this when you need to probe object-level runtime state beyond what watch/getglobal can provide.
| name | flight-profiler-trace |
| description | Trace execution time of Python method invocations in a live process with call stack visualization. Use this to see a hierarchical call tree showing which sub-calls are slow and where time is spent within a function. |
Trace the execution time of a specified method invocation, displaying a call tree with timing. Unlike watch which shows individual invocations, trace reveals the full call hierarchy underneath a function — making it ideal for finding which sub-call is the bottleneck.
Prerequisites: Read the flight-profiler-attach skill first for platform requirements, installation, permissions, and connection details.
-i interval threshold)flight_profiler <pid> --cmd "trace module [class] method [options]" --no-color
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 module-level functionmethod — target method name| Flag | Description | Default |
|---|---|---|
-i, --interval <value> | Only display sub-calls costing more than N milliseconds. Calls below this threshold are hidden from the tree. | 0.1 |
-et, --entrance_time <value> | Only display invocations where the entrance (top-level) cost exceeds N milliseconds. Invocations below this threshold are silently skipped. | 0 |
-d, --depth <value> | Limit call tree display depth. -d 2 shows only direct children of the traced method. When set, ignores -i interval. | -1 (unlimited) |
-nm, --nested-method <value> | Trace a nested (inner) function defined inside the target method. Depth is restricted to 1. | none |
-n, --limits <value> | Maximum number of invocations to capture before stopping | 10 |
-f, --filter_expr <value> | Filter expression on (target, *args, **kwargs). Only invocations where the expression is truthy are traced. For class methods, args[0] is self. | none |
Each captured invocation produces a block:
────────────────────────────────────────────────────────────
🔍 2026-04-19 11:35:38:953 thread=MainThread tid=8722965056 daemon=False cost=90.003ms
[90.003ms] process_order trace_demo_script.py:6
├─ [5.574ms] validate trace_demo_script.py:13
│ └─ [5.52ms] sleep <built-in>
├─ [31.402ms] compute_price trace_demo_script.py:16
│ ├─ [21.285ms] sleep <built-in>
│ └─ [10.074ms] apply_discount trace_demo_script.py:20
│ └─ [10.049ms] sleep <built-in>
└─ [52.99ms] save_to_db trace_demo_script.py:23
└─ [52.949ms] sleep <built-in>
Title line fields:
| Field | Description |
|---|---|
🔍 | trace command icon |
| Timestamp | When the entrance method was called |
thread | Thread name that executed the method |
tid | Thread ID |
daemon | Whether the thread is a daemon thread |
cost | Total execution time of the entrance method (milliseconds) |
Call tree fields (each line):
| Field | Description |
|---|---|
[Nms] | Execution time of that specific call. Color-coded in terminal: >50% of parent = red, >20% = yellow, >5% = green, else faint green |
| Method name | Function name. [await] prefix indicates an async await point |
| Location | filename:lineno for Python methods, <built-in> for C extension methods |
Tree structure: ├─ / └─ show child calls, │ connects sibling levels.
Shows the complete hierarchy with all sub-calls and their timing:
flight_profiler <pid> --cmd "trace __main__ OrderService process_order -n 1" --no-color
🔍 2026-04-19 11:35:38:953 thread=MainThread tid=8722965056 daemon=False cost=90.003ms
[90.003ms] process_order trace_demo_script.py:6
├─ [5.574ms] validate trace_demo_script.py:13
│ └─ [5.52ms] sleep <built-in>
├─ [31.402ms] compute_price trace_demo_script.py:16
│ ├─ [21.285ms] sleep <built-in>
│ └─ [10.074ms] apply_discount trace_demo_script.py:20
│ └─ [10.049ms] sleep <built-in>
└─ [52.99ms] save_to_db trace_demo_script.py:23
└─ [52.949ms] sleep <built-in>
Reading: save_to_db takes 52.99ms (59% of total) — the dominant bottleneck. compute_price takes 31.4ms including its child apply_discount.
flight_profiler <pid> --cmd "trace __main__ compute -n 1" --no-color
🔍 2026-04-19 11:35:42:462 thread=MainThread tid=8722965056 daemon=False cost=21.672ms
[21.672ms] compute trace_demo_script.py:43
├─ [10.104ms] sleep <built-in>
├─ [6.298ms] helper trace_demo_script.py:48
│ └─ [6.269ms] sleep <built-in>
└─ [5.217ms] helper trace_demo_script.py:48
└─ [5.184ms] sleep <built-in>
-d-d 2 shows only the entrance method and its direct children — hides deeper calls:
flight_profiler <pid> --cmd "trace __main__ OrderService process_order -d 2 -n 1" --no-color
🔍 2026-04-19 11:35:51:448 thread=MainThread tid=8722965056 daemon=False cost=90.374ms
[90.374ms] process_order trace_demo_script.py:6
├─ [6.282ms] validate trace_demo_script.py:13
├─ [31.704ms] compute_price trace_demo_script.py:16
└─ [52.336ms] save_to_db trace_demo_script.py:23
Useful for getting an overview of the top-level breakdown without noise from deeper calls.
-i-i 10 hides sub-calls costing less than 10ms. validate (5ms) is hidden:
flight_profiler <pid> --cmd "trace __main__ OrderService process_order -i 10 -n 1" --no-color
🔍 2026-04-19 11:35:52:586 thread=MainThread tid=8722965056 daemon=False cost=92.380ms
[92.38ms] process_order trace_demo_script.py:6
├─ [35.176ms] compute_price trace_demo_script.py:16
│ ├─ [22.783ms] sleep <built-in>
│ └─ [12.343ms] apply_discount trace_demo_script.py:20
│ └─ [12.313ms] sleep <built-in>
└─ [50.889ms] save_to_db trace_demo_script.py:23
└─ [50.844ms] sleep <built-in>
-et-et 50 silently skips entire invocations where total cost < 50ms. Only invocations costing >= 50ms are captured. Unlike -i which filters sub-calls within a tree, -et filters the entire invocation.
flight_profiler <pid> --cmd "trace __main__ OrderService process_order -et 50 -n 1" --no-color
If the method typically takes 90ms, output appears normally. If an invocation only takes 30ms, it is silently dropped and does not count toward -n.
-nmTraces an inner function defined inside the target method. Depth is restricted to 1:
flight_profiler <pid> --cmd "trace __main__ OrderService nested_outer -nm inner_work -n 1" --no-color
🔍 2026-04-19 11:36:04:093 thread=MainThread tid=8722965056 daemon=False cost=12.526ms
[12.526ms] inner_work trace_demo_script.py:27
└─ [12.511ms] sleep <built-in>
Note: the spy message shows nested_outer.inner_work, confirming the nested method was found.
Automatically follows the full call chain depth:
flight_profiler <pid> --cmd "trace __main__ OrderService deep_call_a -n 1" --no-color
🔍 2026-04-19 11:36:05:247 thread=MainThread tid=8722965056 daemon=False cost=6.294ms
[6.294ms] deep_call_a trace_demo_script.py:32
└─ [6.291ms] deep_call_b trace_demo_script.py:35
└─ [6.287ms] deep_call_c trace_demo_script.py:38
└─ [6.268ms] sleep <built-in>
-fOnly trace invocations matching the filter expression. For module-level functions, args[0] is the first argument:
flight_profiler <pid> --cmd "trace __main__ compute -f 'args[0]>=1' -n 1" --no-color
🔍 2026-04-19 11:37:42:600 thread=MainThread tid=8722965056 daemon=False cost=24.215ms
[24.215ms] compute trace_demo_script.py:43
├─ [12.534ms] sleep <built-in>
├─ [6.314ms] helper trace_demo_script.py:48
│ └─ [6.286ms] sleep <built-in>
└─ [5.321ms] helper trace_demo_script.py:48
└─ [5.303ms] sleep <built-in>
For class methods, args[0] is self, so use args[1] for the first real argument.
-i / -et / -d GuideThese three options control what appears in the output at different levels:
| Option | What it filters | Effect |
|---|---|---|
-i (interval) | Individual sub-calls in the tree | Hides branches where the call cost < N ms. The invocation is still captured, just with fewer branches shown. |
-et (entrance_time) | Entire invocations | Silently skips invocations where the total entrance cost < N ms. Does not count toward -n. |
-d (depth) | Tree depth | Truncates the tree at N levels. When set, -i is ignored. |
Common combinations:
# Show only slow invocations, then only their expensive sub-calls
trace __main__ MyClass method -et 100 -i 10 -n 3
# Quick overview: just the top-level breakdown
trace __main__ MyClass method -d 2 -n 1
# Catch everything (debug mode)
trace __main__ MyClass method -i 0 -n 1
If trace produces no output:
flight_profiler <pid> --cmd "module /path/to/file.py" --no-color to verify-et too high — invocations below the threshold are silently skipped (try -et 0)-i too high — sub-calls below the threshold are hidden (try -i 0)flight_profiler <pid> --cmd "trace __main__ handle_request -n 1" --no-color > /tmp/trace_output.txt
-n 1 -d 2 capturing a shallow tree), display the full result directly to the user. If multiple traces were captured, showing just one representative case is sufficient.-d 2 -n 1 for a quick overview, then remove -d to see the full tree-i 10 to focus on sub-calls taking > 10ms, lowering as needed to zoom inwatch to first identify a slow function, then trace to find the bottleneck inside it-et to skip uninteresting fast invocations when the method is called frequentlyflight_profiler/plugins/trace/cli_plugin_trace.pyflight_profiler/plugins/trace/trace_parser.pyflight_profiler/plugins/trace/server_plugin_trace.py