perfetto-mcp

Parses binary Perfetto trace files (protobuf format) and extracts structured performance data including CPU scheduling, memory allocation, GPU rendering, and custom events. Implements protobuf deserialization to convert raw trace bytes into queryable event streams with timestamp, process, thread, and category metadata. Exposes trace contents through MCP tools that clients can invoke to inspect performance characteristics without requiring direct Perfetto UI access.

Implements MCP server protocol to register and expose trace analysis operations as callable tools. Defines tool schemas (name, description, input parameters) that conform to MCP's function-calling specification, allowing LLM clients to discover and invoke trace queries through standard MCP mechanisms. Handles tool invocation routing, parameter validation, and response serialization back to the client.

Filters parsed trace events by criteria such as process ID, thread ID, event category, or time window. Implements in-memory filtering logic that scans the event stream and returns matching subsets. Supports range queries (e.g., 'events between timestamp T1 and T2') to isolate performance anomalies or specific execution phases without re-parsing the entire trace.

Extracts high-level metadata from parsed traces including process list, thread list, trace duration, event counts by category, and timestamp ranges. Generates summary statistics (e.g., 'trace contains 500K CPU events across 8 processes') to give LLMs a quick overview of trace contents without requiring full event enumeration. Implements aggregation logic that scans the event stream once to compute counts and ranges.

Analyzes trace events to identify potential performance issues such as excessive context switches, memory spikes, long blocking operations, or GPU stalls. Implements heuristic-based detection (e.g., 'flag CPU events with >100 context switches per second' or 'alert on memory allocations >100MB in <1s'). Exposes detected anomalies as structured results that LLMs can reason about and correlate with application behavior.

Extracts GPU rendering events from Perfetto traces including frame composition, GPU command submission, and rendering latency. Computes frame timing metrics (frame duration, GPU time, CPU-GPU sync points) and identifies frames exceeding target frame rates (e.g., 60fps, 120fps). Provides per-frame breakdown of GPU work and identifies rendering bottlenecks (GPU stalls, CPU-GPU synchronization delays).

Compares metrics from multiple Perfetto traces to identify performance regressions or improvements. Computes delta metrics (CPU time difference, memory usage change, frame rate variance) between baseline and test traces and flags statistically significant changes. Supports filtering comparisons by event type, process, or time range. Generates regression reports with affected components and severity scores.

Exports trace analysis results in multiple formats (JSON, CSV, HTML reports) for integration with external tools and dashboards. Generates human-readable performance reports with charts, tables, and summary statistics. Supports custom report templates for different analysis types (CPU profiling, memory analysis, frame timing). Exports raw event data for further processing by downstream tools.