Docs: unify TraceLens metrics reference (CSV + TraceIndex SQL) - #981
Open
ajassani wants to merge 18 commits into
Open
Docs: unify TraceLens metrics reference (CSV + TraceIndex SQL)#981ajassani wants to merge 18 commits into
ajassani wants to merge 18 commits into
Conversation
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Map Kernel stream and category kernel-time_ms columns, cover import with checked-in report fixtures, and Black-format the new files.
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Parse perf_params and kernel_details_summary from Python repr into JSON so they are queryable. Kernel rows now come from each unified op's kernel_details_summary with a unified_row_id FK, replacing the flat kernel_summary.csv import. Add gemm_perf, sdpa_perf, and conv_perf satellite tables keyed on unified_row_id for shape-based SQL. Update the how-to schema diagram and tests accordingly. Co-authored-by: Cursor <cursoragent@cursor.com>
The table holds one row per kernel belonging to a specific op (via unified_row_id), not the aggregate kernel_summary.csv sheet. Rename it to op_kernels to avoid colliding with that report sheet name and to reflect that each row is a per-op kernel. Update indexes, ingest, docs diagram, and tests. Co-authored-by: Cursor <cursoragent@cursor.com>
Document what each test in test_trace_index.py verifies so the suite reads as a table of contents for the catalog behavior. Co-authored-by: Cursor <cursoragent@cursor.com>
Add an example-queries section to the trace-index how-to showing depthwise convolution and longest-context attention lookups against the shape satellite tables, so shape questions are SQL filters rather than trace reopens. Co-authored-by: Cursor <cursoragent@cursor.com>
Include sample result tables and short takeaways for the depthwise-convolution and longest-attention example queries so the how-to shows the payoff of the shape satellite tables, not just the SQL. Co-authored-by: Cursor <cursoragent@cursor.com>
Catalog ingest is append/build only. Remove the unused directory scanner and stop exporting import_report_dir; existing CSV reports go through append --report-dir. Tests for real report fixtures now use that public path. Co-authored-by: Cursor <cursoragent@cursor.com>
The HTTP query server and sqlite-sql intentionally run caller-provided SELECT statements. They are already restricted to a single read-only statement and opened with SQLite query_only/mode=ro. Add CodeQL suppressions so that expected use is not reported as SQL injection. Co-authored-by: Cursor <cursoragent@cursor.com>
Cover health, tables, GET/POST /query, write rejection, 404s, and result truncation. Close SQLite connections in the handler; a connection context manager does not close the DB and leaked handles in tests. Co-authored-by: Cursor <cursoragent@cursor.com>
Extract write_stub_trace/write_mini_report fixtures, use a query_server context manager for HTTP server lifecycle, and merge the two server test functions. Drop redundant store-boundary test covered by append/import paths. Co-authored-by: Cursor <cursoragent@cursor.com>
Address Kyle review: document --report-root for generated reports, add trace-index-catalog-schema.md for SQL column lookup (separate from perf-report-columns CSV reference), and cross-link from the how-to. Co-authored-by: Cursor <cursoragent@cursor.com>
Move try/except into handle_query so GET and POST /query return the same 400 JSON errors. Cross-link perf-report-columns (semantics) with catalog schema (SQL mapping). Co-authored-by: Cursor <cursoragent@cursor.com>
Rename perf-report-columns to tracelens-metrics.md with shared intro, an In performance reports section, and an In TraceIndex catalogs section. Remove the separate catalog schema page; update TOC and cross-links. Co-authored-by: Cursor <cursoragent@cursor.com>
ajassani
requested review from
devalshahamd,
gabeweisz and
tsrikris
as code owners
August 30, 2026 23:04
3 tasks
Collaborator
|
LGTM - fix the conflicts and I'll approve |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Tracks #982.
Stacked on #674 (\�jassani/traceindex-feature) so Kyle's doc comments can land separately from the TraceIndex code changes.
Test plan