--- name: pylance-python-profiling description: 'Use when the user wants to profile Python code with Pylance: capture CPU time (Tachyon), trace calls (sys.monitoring), or memory (Memray); profile a whole run or a specific region between two source locations; add sub-region markers; and explore the resulting profile (hot functions, call trees, time slices). Also use for the 3.15+ interpreter requirement and related error guidance.' --- # Pylance Python Profiling Use this skill to drive the `pylancePythonProfiling` capture tool and the `pylancePythonProfileExplorer` analysis tool. Capture produces artifacts on disk plus a sidecar metadata JSON; the explorer loads that metadata and answers paged queries (hot functions, call tree, time-sliced views). ## Tools - `pylancePythonProfiling` — start/stop captures and inspect sessions. One `action` per call. - `pylancePythonProfileExplorer` — load a capture's metadata JSON and query it. Run `{"action":"help"}` on either tool to print its full surface. ## Verified Tool Facts - Backends: CPU = `profiling.sampling` (Tachyon), Trace = `sys.monitoring`, Memory = Memray. - **CPU profiling requires Python 3.15+.** The tool resolves the workspace-selected interpreter (same resolution as the other Pylance MCP tools). If it is below 3.15, capture returns a structured error naming the selected version. Fix by selecting a 3.15+ interpreter or passing `pythonPath` explicitly. - Trace and Memory work on older interpreters (Trace needs 3.12+ for `sys.monitoring`). - Every capture returns a `profilingSessionId` immediately and writes artifacts under an `artifactsDir`, including a `*.metadata.json` sidecar. Pass that metadata path to the explorer, not the raw binary. - Captures own their own session lifecycle; they do not require `pylancePythonDebug`. - The injected handshake and sampler wrapper are code **we add on the fly** — the user's source is never edited. Region boundaries and markers are expressed as `file:line`. ## Actions (`pylancePythonProfiling`) | `action` | Purpose | | ------------------ | ---------------------------------------------------------------------- | | `list` | Show active/completed sessions. | | `status` | Inspect one session (`profilingSessionId`). | | `startCpu` | CPU capture. `mode:"launch"` (script/module) or `mode:"attach"` (pid). | | `startCpuRegion` | CPU capture of one region only (launch mode). See below. | | `stopCpu` | Stop/finalize a CPU session; returns saved artifact paths. | | `startTracing` | `sys.monitoring` trace of a script/module (launch only). | | `stopTracing` | Cooperative stop for a trace session. | | `takeHeapSnapshot` | One-shot Memray capture. | | `stop` | Terminate a session and drop it from the in-memory list. | | `help` | Print full help. | CPU sampling options (apply to `startCpu` and `startCpuRegion`): `samplingRate` (e.g. `"1khz"`), `duration` (seconds), `samplingMode` (`wall|cpu|gil|exception`, default `cpu`), `allThreads`, `native`, `noGc`, `opcodes`, `blocking`, `subprocesses`. ## Scenario 1 — Profile a whole run Launch a script under the CPU sampler, then load the result: ```json { "action": "startCpu", "mode": "launch", "script": "/path/to/app.py", "pythonPath": "/path/to/python", "samplingRate": "1khz" } ``` Attach to an already-running process instead: ```json { "action": "startCpu", "mode": "attach", "pid": 12345, "pythonPath": "/path/to/python" } ``` Bound an attach by wall-clock time: ```json { "action": "startCpu", "mode": "attach", "pid": 12345, "samplingMode": "wall", "duration": 30 } ``` When done (launch captures finalize on their own; attach/duration captures too), retrieve artifacts: ```json { "action": "stopCpu", "profilingSessionId": "pyprof-..." } ``` ## Scenario 2 — Profile a specific region (`startCpuRegion`) Use this when only part of a run matters (a hot function, a request handler) and you want the sampler live from the region's first instruction with no attach-latency contamination. Launch mode only. ```json { "action": "startCpuRegion", "mode": "launch", "script": "/path/to/app.py", "pythonPath": "/path/to/python", "regionStartLocation": "app.py:42", "regionStopLocation": "app.py:88" } ``` How it works (no user code edits): 1. The target launches under an injected handshake. When execution first reaches `regionStartLocation` the target parks. 2. Tachyon attaches to the parked target, then the target is released — so the region is sampled from its first instruction. Attach cost is paid while parked, outside the measured region. 3. When execution reaches `regionStopLocation`, the sampler is detached and its data flushed before the target resumes its tail. Region bounds are recorded in metadata as `region.startTimeMs`/`region.endTimeMs`, so the explorer can slice CPU views exactly to the region with `startTimeMs`/`endTimeMs`. Guidance: - Locations are `file:line`; relative paths resolve against the target's working directory. - The start line must actually execute, or the region never starts (the tool reports the target exited before reaching the start location). - Use `stopCpu` to fetch artifacts or to stop early. ## Scenario 3 — Sub-region markers Markers label points **inside** the region without parking or re-attaching. Use them to break one attach into several labeled sub-regions (cheaper than many tiny `startCpuRegion` calls) and to annotate phases. Pass `regionMarkers` as `"label@file:line"` (or just `"file:line"`): ```json { "action": "startCpuRegion", "mode": "launch", "script": "/path/to/app.py", "pythonPath": "/path/to/python", "regionStartLocation": "app.py:42", "regionStopLocation": "app.py:88", "regionMarkers": ["load@app.py:50", "compute@app.py:64", "render@app.py:80"] } ``` Each time execution reaches a marker line inside the region, a labeled timestamp (ms from region start) is recorded. The explorer surfaces them under `region.markers`; use adjacent marker times as `startTimeMs`/`endTimeMs` to slice a sub-region. ## Scenario 4 — Trace and memory ```json {"action":"startTracing","mode":"launch","module":"mypackage.app","pythonPath":"/path/to/python"} {"action":"stopTracing","profilingSessionId":"pyprof-..."} ``` ```json { "action": "takeHeapSnapshot", "mode": "launch", "script": "/path/to/app.py", "pythonPath": "/path/to/python", "traceNativeMemory": true } ``` ## Exploring results (`pylancePythonProfileExplorer`) Load the capture's metadata JSON, then query views with the returned `profileId`: ```json {"action":"loadCpuProfile","filePath":"/path/to/artifactsDir/cpu.metadata.json"} {"action":"query","profileId":"cpu-...","view":"summary"} {"action":"query","profileId":"cpu-...","view":"bottomUp"} {"action":"query","profileId":"cpu-...","view":"search","queryText":"compute"} ``` - CPU views: `summary | callTree | bottomUp | eventLog | search | nodeContext`. - Trace views: `summary | events | byCategory | byProcessThread | timelineSlices | search`. - Heap views: `summary | allocations | search`. - For region captures, `loadCpuProfile` returns a `region` block (bounds + markers). Slice a CPU view to the region or a sub-region with `startTimeMs`/`endTimeMs` (both are ms from start). - `search` `queryText` syntax: space-separated terms OR; `+term` AND; `/regex/`; `"phrase"` exact. - `/regex/` format — a common, safe subset, always case-insensitive: - Supported: literals and escaped metacharacters; `.`; character classes `[...]`/`[^...]`/ranges and `\d \D \w \W \s \S`; anchors `^` `$`; groups `( )` and `(?: )`; alternation `|`; quantifiers `* + ? {m} {m,} {m,n}` (a trailing lazy `?` is accepted); control escapes `\n \r \t \f \v \0`. - Not supported (the term degrades to a literal substring match): word boundaries `\b` `\B`, named groups, back-references, look-around `(?=) (?!) (?<=) (?