perfetto-tracing

name: "perfetto-tracing" description: "Guides the capture and optimization of Perfetto traces in benchmarks. Invoke when the user wants to trace performance, analyze bottlenecks, or generate pftrace files."

Perfetto Tracing Guide

This skill provides instructions on how to enable, capture, and optimize Perfetto tracing for benchmarks in the Skity project. Future agents can rely on this skill to properly configure and run benchmarks when performance tracing is required.

1. How to Enable Tracing

The Perfetto SDK is integrated via a CMake option. By default, it is turned OFF to ensure zero overhead.

• Build Command: Pass -DSKITY_BENCH_ENABLE_PERFETTO=ON to CMake when configuring the project.
• Run Benchmark: Execute the compiled benchmark binary (e.g., ./test/bench/skity_hw_render_bench).
• Trace Output: The session will automatically save the trace file to output/hw_benchmarks.pftrace.
• Verify: Look for the log "Perfetto Tracing is ENABLED" in the terminal.
• Analyze: Open ui.perfetto.dev in the browser and drag the .pftrace file into it.
• Identification:
  • Process: Look for skity_hw_bench.
  • Thread: Look for main_bench_thread.
  • Benchmark: The outer scope event is named after the benchmark (e.g., Tiger_2000_Metal_MSAA).
  • Iteration: Each loop cycle is marked as Iteration_N.

2. When to Invoke This Skill

This skill should be invoked when:

• Analyzing benchmark performance bottlenecks.
• The user requests a "trace" or "profile" of a specific rendering operation.
• Debugging unexpected latency in the rendering pipeline.

3. Strategies for Long Traces

When dealing with long-running benchmarks or many iterations, trace buffers can easily overflow, resulting in massive trace files or data loss. Use the following strategies to restrict the scope:

Precise Filtering (Recommended)

Do not run all benchmarks at once. Use the Google Benchmark filter to isolate the target:

./test/bench/skity_hw_render_bench --benchmark_filter="^TargetBenchmarkName$"

Limit Iterations

Restrict the benchmark iterations to prevent excessive duplicate events from flooding the trace buffer:

./test/bench/skity_hw_render_bench --benchmark_filter="^TargetBenchmarkName$" --benchmark_min_time=0.1

(Alternatively, use --benchmark_repetitions=1 if supported).

Buffer Optimization

If the trace is still too large or losing data, check the perfetto::TraceConfig in the StartPerfettoSession() function of hw_benchmarks.cc.

• Ensure the buffer size is adequate (e.g., 1024 * 1024 for 1GB).
• Policy: Use DISCARD instead of RING_BUFFER when internal Skity tracing is enabled. This prevents overwriting the initial metadata (string mappings), which would cause "sequences dropped" errors in the UI.
• Important: Call tracing_session->FlushBlocking() before stopping the session.

4. Skity Internal Events

Skity internal events are tracked under the "skity2d" category. Ensure RegisterSkityPerfettoHandler() is correctly initialized in StartPerfettoSession() so that internal Skity function durations are captured alongside Benchmark_Draw and Target_Flush.