This release is a pre-release and may not be stable for production use.
CUTracer Python Module
Python tools for CUTracer trace validation, parsing, and analysis.
Overview
The cutracer Python package provides a comprehensive framework for working with CUTracer trace files. This module is designed to be:
- Reusable: Import and use in your own Python scripts
- Testable: Full unittest suite with real trace data
- Type-safe: Type hints and mypy compatibility
- Extensible: Plugin architecture for future enhancements
Installation
For Development
cd /path/to/CUTracer/python
pip install -e ".[dev]"
For Production Use
cd /path/to/CUTracer/python
pip install .
Features
Trace Validation (Current)
- JSON Validation: Validate NDJSON trace files (mode 2) for syntax and schema compliance
- Text Validation: Validate text-format trace files (mode 0) for format compliance
- Cross-Format Consistency: Compare different trace formats for data consistency
Planned Features
- Trace Parsing: Parse trace files into structured Python objects
- Analysis Tools: Instruction histograms, performance metrics, trace comparison
- Format Conversion: Convert between different trace formats
- Compression Support: Handle zstd-compressed traces (mode 1)
Usage
CLI
After installation, the cutracer command provides a unified interface for
tracing, querying, and analyzing CUDA traces:
# Trace a CUDA application (requires cutracer.so — see main README for build)
export CUTRACER_LIB_PATH=/path/to/CUTracer/lib
cutracer trace -i tma_trace -- python test.py
# Validate trace files
cutracer validate kernel_trace.ndjson
# Query and filter trace data
cutracer query trace.ndjson --filter "warp=24"
# Analyze traces
cutracer analyze warp-summary trace.ndjson
Python API
from cutracer.validation import (
validate_json_trace,
validate_text_trace,
compare_trace_formats,
)
# Validate JSON trace
result = validate_json_trace("kernel_trace.ndjson")
if result["valid"]:
print(f"✓ Valid JSON trace with {result['record_count']} records")
else:
print(f"✗ Validation failed: {result['errors']}")
# Validate text trace
result = validate_text_trace("kernel_trace.log")
if result["valid"]:
print(f"✓ Valid text trace")
else:
print(f"✗ Validation failed: {result['errors']}")
# Compare two formats
result = compare_trace_formats("kernel_trace.log", "kernel_trace.ndjson")
if result["consistent"]:
print("✓ Formats are consistent")
else:
print(f"✗ Inconsistencies found: {result['differences']}")
Module Structure
python/
├── cutracer/ # Main package
│ ├── __init__.py # Package entry point with version
│ └── validation/ # Validation framework
│ ├── __init__.py # Validation API exports
│ ├── schema_loader.py # JSON Schema loader
│ ├── json_validator.py # JSON syntax & schema validation
│ ├── text_validator.py # Text format validation
│ ├── consistency.py # Cross-format consistency checks
│ └── schemas/ # JSON Schema definitions
│ ├── __init__.py
│ ├── reg_trace.schema.json
│ ├── mem_trace.schema.json
│ ├── opcode_only.schema.json
│ └── delay_config.schema.json
├── tests/ # Unit tests
│ ├── __init__.py
│ ├── test_base.py # Base test class and utilities
│ ├── test_schemas.py # Schema loading tests
│ ├── test_json_validator.py # JSON validation tests
│ ├── test_text_validator.py # Text validation tests
│ ├── test_consistency.py # Consistency check tests
│ └── example_inputs/ # Real trace data for tests
│ ├── reg_trace_sample.ndjson
│ ├── reg_trace_sample.log
│ ├── invalid_syntax.ndjson
│ └── invalid_schema.ndjson
├── pyproject.toml # Modern Python project config
└── README.md # This file
Development
Running Tests
cd python/
# Run all tests
python -m unittest discover -s tests -v
# Run specific test file
python -m unittest tests.test_json_validator -v
Type Checking
cd python/
mypy cutracer/
Code Formatting
# From project root directory
./format.sh format
# Or manually with ufmt
ufmt format python/
usort format python/
Running All Checks
# Format code
./format.sh format
# Type check
mypy cutracer/
# Run tests
python -m unittest discover -s tests -v
Validation Details
JSON Trace Validation
The JSON validator checks:
- Syntax: Valid JSON format on each line (NDJSON)
- Schema: Correct field types and structure per JSON Schema
- Required Fields:
message_type,ctx,kernel_launch_id,trace_index,timestamp,sass, etc. - Register Values: Arrays of integers with proper format
- CTA/Warp IDs: Valid integer ranges
Text Trace Validation
The text validator checks:
- Format Patterns: Correct CTX/CTA/warp header patterns
- Register Output: Proper hex format (e.g.,
Reg0_T00: 0x...) - Memory Access: Valid memory address patterns
Consistency Validation
The consistency validator compares:
- Record Counts: Same number of records in both formats
- Content Matching: Same kernel IDs, trace indices, SASS strings
- Timestamp Order: Consistent ordering between formats
Trace Format Reference
JSON Format (NDJSON - Mode 2)
Each line is a JSON object with the following structure:
{
"message_type": "reg_trace",
"ctx": "0x58a0c0",
"kernel_launch_id": 0,
"trace_index": 0,
"timestamp": 1762026820167834792,
"sass": "LDC R1, c[0x0][0x28] ;",
"pc": 0,
"opcode_id": 0,
"warp": 0,
"cta": [0, 0, 0],
"regs": [[0, 0, 0, ...]]
}
Text Format (Mode 0)
Human-readable format with CTX headers and register values:
CTX 0x58a0c0 - CTA 0,0,0 - warp 0 - LDC R1, c[0x0][0x28] ;:
* Reg0_T00: 0x0000000000000000 Reg0_T01: 0x0000000000000000 ...
Contributing
- Install development dependencies:
pip install -e ".[dev]" - Make your changes
- Run tests:
python -m unittest discover -s tests -v - Run type checker:
mypy cutracer/ - Format code:
./format.sh format - Submit a pull request
License
MIT License - See LICENSE file for details.
Support
For issues and questions, please open an issue on the CUTracer GitHub repository.
1 maintainer
Release files for cutracer 0.3.1.dev20260823072957
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cutracer-0.3.1.dev20260823072957.tar.gz | 144.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cutracer-0.3.1.dev20260823072957-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 281.4 kB
Release files / cutracer-0.3.1.dev20260823072957.tar.gz
| Download URL | cutracer-0.3.1.dev20260823072957.tar.gz |
|---|---|
| Size | 144.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9041f725baa6d8791da20f8469ef95f005114348a5e53eba9da25f429372d15d
|
|
BLAKE2b-256 checksum How to use checksums |
fd1e40526a632be0c7d2040db4499c772b2f35bb35cf9faf9c78026af237db1b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 23, 2026.
Transparency logRelease files / cutracer-0.3.1.dev20260823072957-py3-none-any.whl
| Download URL | cutracer-0.3.1.dev20260823072957-py3-none-any.whl |
|---|---|
| Size | 136.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e325061d7825ce3bc6db9ff733b3cf84e730a177993b87f971342145ddbf2c0e
|
|
BLAKE2b-256 checksum How to use checksums |
c0fb8b19c8c55fe4ea1bb726dfa227fd46cb452b0986dad34a9fa37461a53e7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.13
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 23, 2026.
Transparency log
