macos-perf

What this skill does

# macos-perf

## Purpose
This skill enables monitoring and profiling macOS system performance using native tools, focusing on CPU, memory, thermal, and power metrics to identify bottlenecks and optimize applications.

## When to Use
Use this skill for diagnosing high CPU usage in apps, investigating memory leaks, profiling resource-intensive processes, checking thermal states during heavy workloads, or analyzing power consumption on macOS devices.

## Key Capabilities
- Monitor real-time system metrics via Activity Monitor or `top/htop` for CPU, memory, and network usage.
- Profile applications with Instruments, capturing detailed traces for CPU, memory, and energy.
- Check memory pressure using `vm_stat` to detect low-memory conditions.
- Query thermal state via `powermetrics` for CPU/GPU temperatures and fan speeds.
- Analyze power metrics with `powermetrics` to measure battery drain and efficiency.
- Use command-line tools like `top -o cpu` for sorted process lists or `instruments -s devices` for available templates.

## Usage Patterns
Invoke this skill in scripts for automated monitoring or integrate into AI workflows for real-time analysis. For example, run periodic checks in a loop for server-like macOS setups, or trigger profiling when an app exceeds resource thresholds. Always specify exact tools and flags based on the task; e.g., use `top` for quick views and Instruments for deep dives. If integrating with automation, export data to JSON for parsing.

## Common Commands/API
- Use `top -o cpu -s 1` to display processes sorted by CPU usage, updating every second; pipe output to `grep` for filtering, e.g., `top -o cpu | grep "MyApp"`.
- Check memory pressure with `vm_stat | grep "Pages"` to get free pages; sample code:
  ```
  output = subprocess.run(['vm_stat'], capture_output=True).stdout
  free_pages = int(re.search(r'free:\s+(\d+)', output.decode()).group(1))
  ```
- Run `powermetrics --samplers cpu,thermal -i 1000` for CPU and thermal data every 1 second.
- Launch Instruments via CLI: `instruments -w <device> -t Time Profiler -D output.trace /path/to/app`; use exported .trace files for analysis.
- For thermal state, use `ioreg -l | grep "Ambient" ` to parse ambient temperature from system registry.
- No API keys required for these tools; they run natively on macOS.

## Integration Notes
Integrate by wrapping commands in Python or shell scripts; set environment variables for custom paths, e.g., export `INSTRUMENTS_PATH=/Applications/Xcode.app/Contents/Developer/usr/bin/instruments`. For data export, use `plutil` to convert .plist outputs to JSON. If combining with other skills, ensure macOS version compatibility (e.g., Instruments requires Xcode); check via `sw_vers -productVersion`. Avoid running multiple intensive tools simultaneously to prevent resource contention.

## Error Handling
Check command exit codes; for example, if `top` fails, verify with `echo $?` and handle by logging errors or retrying. For Instruments, parse stderr for messages like "Template not found" and fallback to alternatives. Use try-except in scripts, e.g.:
  ```
  try:
      result = subprocess.run(['instruments', '-t', 'Time Profiler'], check=True)
  except subprocess.CalledProcessError as e:
      print(f"Error: {e.returncode} - {e.output}")
  ```
Common issues include permission errors (run with sudo) or missing dependencies (install Xcode command line tools via `xcode-select --install`).

## Concrete Usage Examples
1. To monitor CPU usage of a specific process: Run `top -pid <processID> -o cpu` in a loop script, then analyze output to alert if usage > 80%; example script line: `while true; do top -pid 1234 -l 1 | grep CPU; sleep 5; done`.
2. For profiling an app's memory: Use `instruments -t Allocations -D profile.trace /Applications/MyApp.app`, then open the trace in Instruments GUI to identify leaks; integrate by scripting: `instruments ... && open profile.trace`.

## Graph Relationships
- Related to: macos cluster (e.g., macos-core for basic system ops), performance tag (links to general profiling skills), profiling tag (connects to app optimization tools).
- Dependencies: Requires macos cluster skills for foundational access; no direct API links.