diff --git a/extra/mcp/eval_guide.md b/extra/mcp/eval_guide.md index b67ccbe8..d061198b 100644 --- a/extra/mcp/eval_guide.md +++ b/extra/mcp/eval_guide.md @@ -1,7 +1,7 @@ # Tracy MCP eval guide -This document covers the bindings-layer detail that the curated catalog -(`tracy://catalog`) and analysis guidance (`tracy://prompt`) do not. +This document covers the bindings-layer detail that the analysis +guidance (`tracy://prompt`) does not. ## ctx @@ -21,6 +21,9 @@ data surface. Common entry points: - Threads: `get_threads()`, `get_thread_name(tid)`, `get_thread_context_switches(tid)` - Messages / plots / locks / memory / callstacks: `get_messages()`, `get_plots()`, `get_locks()`, `get_memory_events()`, `get_callstack_frames(...)` +- Sections: `get_sections()` — timed code sections from + `TracySectionEnter`/`TracySectionLeave` instrumentation. Returns a list of + `{start, end, text}` dicts (start/end in ns). - Capture metadata: `get_capture_name()`, `get_capture_program()`, `get_first_time()`, `get_last_time()`, `get_resolution()`, `get_host_info()` @@ -41,24 +44,23 @@ Run `print([m for m in dir(ctx) if not m.startswith('_')])` for the full list. - Source-location IDs from `get_all_zone_source_locations()` are the join key between zone-name lookups and per-callsite queries. -## Translating catalog entries to ctx Python +## Common query patterns -The catalog (`tracy://catalog`) lists curated queries. Each maps to a small -Python snippet: +Small Python snippets for the queries you'll reach for most often: ```python -# zone_list — top 10 hottest zones by total time +# top 10 hottest zones by total time top = sorted(ctx.get_all_zone_stats().items(), key=lambda kv: kv[1].total, reverse=True)[:10] for k, v in top: print(f"{v.total/1e6:.2f}ms count={v.count} {k}") -# frame_list — primary frame set timing +# primary frame set timing times = ctx.get_frame_times() # ns per frame print(f"frames={len(times)} avg={sum(times)/len(times)/1e6:.2f}ms " f"p99={sorted(times)[int(len(times)*0.99)]/1e6:.2f}ms") -# zone_stats for a named zone — find the srcloc id, then drill in +# stats for a named zone — find the srcloc id, then drill in import re matches = [k for k in ctx.get_all_zone_stats() if k.startswith("MyFunc ")] sid = int(re.search(r"<(\d+)>$", matches[0]).group(1)) diff --git a/extra/mcp/tracy_mcp.py b/extra/mcp/tracy_mcp.py index f860ce87..1b8524c0 100644 --- a/extra/mcp/tracy_mcp.py +++ b/extra/mcp/tracy_mcp.py @@ -259,8 +259,7 @@ def _prompt_resource() -> str: @mcp_server.resource("tracy://eval-guide") def _eval_guide_resource() -> str: """Bindings-layer guide for the eval tool: ctx object model, time units, - source-location ID semantics, and worked examples translating catalog - entries into ctx Python.""" + source-location ID semantics, and worked examples of common ctx queries.""" return _read_text(_EVAL_GUIDE_PATH) diff --git a/python/bindings/ServerModule.cpp b/python/bindings/ServerModule.cpp index d2bbb772..9bb6738a 100644 --- a/python/bindings/ServerModule.cpp +++ b/python/bindings/ServerModule.cpp @@ -214,6 +214,20 @@ PYBIND11_MODULE( TracyServerBindings, m ) return w.GetMessages().size(); } ) + // --- Sections --- + .def( "get_sections", []( const Worker& w ) { + py::list result; + for( auto& s : w.GetSections() ) + { + py::dict d; + d["start"] = s.start.Val(); + d["end"] = s.end.Val(); + d["text"] = std::string( w.GetString( s.text ) ); + result.append( d ); + } + return result; + } ) + // --- Source locations / zones --- .def( "get_src_loc", []( const Worker& w, int16_t id ) { return w.GetSourceLocation( id );