Enhance README and UI to support NDJSON and compressed file formats (#9)

FindHao · facebook-github-bot · commit f48d06091bde · 2025-06-09T11:50:20.000-07:00
Summary: Updated the README to clarify that trace logs are generated in NDJSON format and added documentation for supported file formats. Enhanced the DataSourceSelector and WelcomeScreen components to accept NDJSON and .gz files, updating error messages and file input prompts accordingly. - README.md: Specify NDJSON trace logs and supported file formats. - New docs/README.md: Add documentation structure and screenshots. - DataSourceSelector.tsx: Update file type validation and input acceptance. - WelcomeScreen.tsx: Modify prompts to reflect support for NDJSON and compressed files. Pull Request resolved: #9 Reviewed By: xuzhao9 Differential Revision: D75914353 Pulled By: FindHao fbshipit-source-id: 00a7ed88aecc57fe5a3ad59323750be5d5e96268
diff --git a/README.md b/README.md
@@ -104,7 +104,7 @@ def your_kernel():
     pass
 
 compiled_kernel = torch.compile(your_kernel)
-result = compiled_kernel()  # This will generate trace logs in ./logs/
+result = compiled_kernel()  # This will generate NDJSON trace logs in ./logs/
 
 # The trace files can then be analyzed using the web interface
 ```
@@ -115,9 +115,29 @@ result = compiled_kernel()  # This will generate trace logs in ./logs/
 
 **Visit [https://pytorch-labs.github.io/tritonparse/](https://pytorch-labs.github.io/tritonparse/)** to use the tool directly in your browser:
 
-1. **Open your local trace file** directly in the browser
+1. **Open your local trace file** (NDJSON or .gz format) directly in the browser
 2. **Explore the visualization** using the Overview and Code Comparison tabs
 
+**Supported File Formats:**
+- `.ndjson` - Newline Delimited JSON trace files
+- `.gz` - Gzip compressed trace files
+
+#### Interface Overview
+
+Once you load a trace file, you'll see the main interface with several key components:
+
+**Kernel Overview & Details:**
+
+![Kernel Overview](docs/screenshots/kernel-overview.png)
+
+*The main interface showing the kernel list, compilation metadata, call stack, and navigation links to different IR representations.*
+
+**Code Comparison View:**
+
+![Code Comparison](docs/screenshots/code-comparison.png)
+
+*Side-by-side comparison of different IR stages (e.g., TTGIR and PTX) with synchronized line highlighting and interactive navigation.*
+
 #### Option B: Local Development (For Contributors)
 
 For contributors working on the website:
@@ -154,6 +174,9 @@ tritonparse/
 │   ├── package.json          # Node.js dependencies
 │   ├── vite.config.ts        # Vite configuration
 │   └── dist/                 # Built application (after build)
+├── docs/                     # Documentation and assets
+│   ├── README.md             # Documentation guidelines
+│   └── screenshots/          # Screenshots for README
 ├── tests/                    # Test files and example traces
 │   ├── test_add.py           # Example Triton kernel test
 │   ├── unit_tests.py         # Unit tests
@@ -243,12 +266,6 @@ Each stage can be inspected and compared to understand optimization transformati
 tritonparse.structured_logging.init("/custom/log/path/")
 ```
 
-### Source Mapping Extraction
-
-```bash
-python tritonparse/extract_source_mappings.py input.ndjson output_mapped.ndjson
-```
-
 ## 🤝 Contributing
 
 1. Fork the repository
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,13 @@
+# Documentation
+
+This directory contains documentation assets for the TritonParse project.
+
+## Directory Structure
+
+```
+docs/
+├── README.md          # This file
+└── screenshots/       # Screenshots for README and documentation
+    ├── kernel-overview.png     # Main interface with kernel list and details
+    └── code-comparison.png     # Code comparison view
+```
diff --git a/docs/screenshots/code-comparison.png b/docs/screenshots/code-comparison.png
diff --git a/docs/screenshots/kernel-overview.png b/docs/screenshots/kernel-overview.png
diff --git a/website/index.html b/website/index.html
@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/logo.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Triton Parse</title>
+    <title>TritonParse</title>
   </head>
   <body>
     <div id="root"></div>
diff --git a/website/src/App.tsx b/website/src/App.tsx
@@ -353,7 +353,7 @@ function App() {
               }}
               title="Back to home"
             >
-              Triton Parse
+              TritonParse
             </h1>
 
             {/* Data source selector (only show when data is loaded or when on the welcome screen) */}
diff --git a/website/src/components/DataSourceSelector.tsx b/website/src/components/DataSourceSelector.tsx
@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useState } from "react";
 
 interface DataSourceSelectorProps {
   onFileSelected: (file: File) => void;
@@ -9,32 +9,34 @@ interface DataSourceSelectorProps {
 /**
  * Component for selecting data sources - either local file or URL
  */
-const DataSourceSelector: React.FC<DataSourceSelectorProps> = ({
-  onFileSelected,
-  onUrlSelected,
-  isLoading
-}) => {
+const DataSourceSelector: React.FC<DataSourceSelectorProps> = ({ onFileSelected, onUrlSelected, isLoading }) => {
   const [showUrlInput, setShowUrlInput] = useState(false);
-  const [url, setUrl] = useState('');
+  const [url, setUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
 
   const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const files = e.target.files;
     if (files && files.length > 0) {
       const file = files[0];
-      if (file.type === 'application/json' || file.name.endsWith('.json')) {
+
+      // Support NDJSON and compressed files only
+      const fileName = file.name.toLowerCase();
+      const isValidFile =
+        fileName.endsWith(".ndjson") || fileName.endsWith(".gz") || file.type === "application/x-ndjson";
+
+      if (isValidFile) {
         setError(null);
         onFileSelected(file);
       } else {
-        setError('Please select a JSON file');
+        setError("Please select an NDJSON or compressed file");
       }
     }
   };
 
   const handleUrlSubmit = (e: React.FormEvent) => {
     e.preventDefault();
     if (!url.trim()) {
-      setError('Please enter a URL');
+      setError("Please enter a URL");
       return;
     }
 
@@ -44,7 +46,7 @@ const DataSourceSelector: React.FC<DataSourceSelectorProps> = ({
       setError(null);
       onUrlSelected(url);
     } catch (err) {
-      setError('Please enter a valid URL');
+      setError("Please enter a valid URL");
     }
   };
 
@@ -56,7 +58,7 @@ const DataSourceSelector: React.FC<DataSourceSelectorProps> = ({
           <label
             htmlFor="fileInput"
             className={`inline-flex items-center px-4 py-2 border border-gray-300 rounded-md font-medium text-sm text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 cursor-pointer ${
-              isLoading ? 'opacity-50 cursor-not-allowed' : ''
+              isLoading ? "opacity-50 cursor-not-allowed" : ""
             }`}
           >
             {/* SVG icon representing a paperclip/attachment for the file upload button */}
@@ -72,12 +74,12 @@ const DataSourceSelector: React.FC<DataSourceSelectorProps> = ({
                 clipRule="evenodd"
               />
             </svg>
-            Open Local JSON
+            Open Local File
           </label>
           <input
             type="file"
             id="fileInput"
-            accept=".json,application/json"
+            accept=".ndjson,.gz,application/x-ndjson,application/gzip"
             onChange={handleFileChange}
             disabled={isLoading}
             className="hidden"
@@ -89,7 +91,7 @@ const DataSourceSelector: React.FC<DataSourceSelectorProps> = ({
           type="button"
           onClick={() => setShowUrlInput(!showUrlInput)}
           className={`inline-flex items-center px-4 py-2 border border-gray-300 rounded-md font-medium text-sm text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 ${
-            isLoading ? 'opacity-50 cursor-not-allowed' : ''
+            isLoading ? "opacity-50 cursor-not-allowed" : ""
           }`}
           disabled={isLoading}
         >
@@ -118,14 +120,14 @@ const DataSourceSelector: React.FC<DataSourceSelectorProps> = ({
               type="url"
               value={url}
               onChange={(e) => setUrl(e.target.value)}
-              placeholder="Enter JSON file URL"
+              placeholder="Enter NDJSON file URL"
               className="flex-1 p-2 border border-gray-300 rounded-l-md shadow-sm focus:ring-indigo-500 focus:border-indigo-500 sm:text-sm"
               disabled={isLoading}
             />
             <button
               type="submit"
               className={`inline-flex items-center px-4 py-2 border border-transparent rounded-r-md shadow-sm text-sm font-medium text-white bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 ${
-                isLoading ? 'opacity-50 cursor-not-allowed' : ''
+                isLoading ? "opacity-50 cursor-not-allowed" : ""
               }`}
               disabled={isLoading}
             >
diff --git a/website/src/components/WelcomeScreen.tsx b/website/src/components/WelcomeScreen.tsx
@@ -14,15 +14,24 @@ const WelcomeScreen: React.FC<WelcomeScreenProps> = ({ loadDefaultData, handleFi
   const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const files = e.target.files;
     if (files && files.length > 0) {
-      handleFileSelected(files[0]);
+      const file = files[0];
+
+      // Support NDJSON and compressed files only
+      const fileName = file.name.toLowerCase();
+      const isValidFile = fileName.endsWith(".ndjson") || fileName.endsWith(".gz");
+
+      if (isValidFile) {
+        handleFileSelected(file);
+      }
     }
   };
 
   return (
     <div className="flex flex-col items-center justify-center px-4 py-16 max-w-4xl mx-auto text-center">
-      <h2 className="text-2xl font-bold text-gray-800 mb-6">Welcome to Triton Parse</h2>
+      <h2 className="text-2xl font-bold text-gray-800 mb-6">Welcome to TritonParse</h2>
       <p className="mb-8 text-gray-600">
-        Load a Triton log file to analyze compiled kernels and their IR representations.
+        Load a Triton log file to analyze compiled kernels and their IR representations. Supports NDJSON and compressed
+        (.gz) files.
       </p>
 
       <div className="grid grid-cols-1 md:grid-cols-3 gap-8 w-full max-w-4xl mb-10">
@@ -77,12 +86,12 @@ const WelcomeScreen: React.FC<WelcomeScreenProps> = ({ loadDefaultData, handleFi
             </svg>
           </div>
           <h3 className="text-lg font-medium text-gray-800 mb-2">Local File</h3>
-          <p className="text-sm text-gray-600 mb-4">Open a Triton log file from your device</p>
+          <p className="text-sm text-gray-600 mb-4">Open a Triton log file from your device (NDJSON or .gz)</p>
           <label htmlFor="welcomeFileInput" className="absolute inset-0 cursor-pointer" aria-label="Open local file" />
           <input
             type="file"
             id="welcomeFileInput"
-            accept=".json,application/json"
+            accept=".ndjson,.gz,application/x-ndjson,application/gzip"
             onChange={handleFileChange}
             className="hidden"
           />
@@ -119,9 +128,9 @@ const WelcomeScreen: React.FC<WelcomeScreenProps> = ({ loadDefaultData, handleFi
       </div>
 
       <div className="text-sm text-gray-500 max-w-2xl">
-        <h4 className="font-medium mb-2">About Triton Parse</h4>
+        <h4 className="font-medium mb-2">About TritonParse</h4>
         <p>
-          Triton Parse helps you analyze Triton GPU kernels by visualizing the compilation process across different IR
+          TritonParse helps you analyze Triton GPU kernels by visualizing the compilation process across different IR
           stages.
         </p>
       </div>

Original file line number	Diff line number	Diff line change
`@@ -353,7 +353,7 @@ function App() {`
`353`	`353`	`}}`
`354`	`354`	`title="Back to home"`
`355`	`355`	`>`
`356`		`- Triton Parse`
	`356`	`+ TritonParse`
`357`	`357`	`</h1>`
`358`	`358`
`359`	`359`	`{/* Data source selector (only show when data is loaded or when on the welcome screen) */}`