Metadata-Version: 2.5
Name: xcl-lens
Version: 0.3.0
Summary: RCCL/NCCL log parser and analyzer
Project-URL: Homepage, https://github.com/alephpiece/hg-misc-tools
Project-URL: Repository, https://github.com/alephpiece/hg-misc-tools
Project-URL: Issues, https://github.com/alephpiece/hg-misc-tools/issues
Author-email: alephpiece <wangan.cs@gmail.com>
License: MIT
License-File: LICENSE
Keywords: gpu,logging,nccl,parser,rccl
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: pandas>=2.0.0
Requires-Dist: typer>=0.23
Description-Content-Type: text/markdown

xcl-lens
========

RCCL/NCCL log parser and analyzer.

## Installation

### From PyPI

#### Using pipx (recommended for CLI use)

```bash
pipx install xcl-lens
```

#### Using uv

```bash
uv tool install xcl-lens
```

#### Using pip

```bash
pip install xcl-lens
```

### From Source

#### Using pipx

```bash
pipx install .
```

#### Using uv

```bash
# Install in editable mode
uv pip install -e .

# Or using uv's native install
uv tool install .
```

#### Using pip

```bash
pip install -e .
```

## Usage

### Process Existing Files

```bash
xcl-lens rccl-log.txt
xcl-lens --summary rccl.*.log
```

When multiple files are supplied, each file must contain a communicator `Init START` identity and
the files must collectively form one complete `(commId, nranks)` global-rank set. Ambiguous,
incomplete, or duplicate inputs are rejected with diagnostics instead of being silently merged.
Automatic detection of mixed stdout requires the rccl-tests rank table to establish trusted process
identities.

### Process stdin

```bash
cat rccl-log.txt | xcl-lens
```

### Options

- `--summary` suppresses the raw log.
- `-v` extends summary reports.
- `--hosts` filters entries by hostname.
- `--prefix-ranks` filters the numeric `[n]` field in RCCL/NCCL log prefixes. It does not select
  communicator global ranks.

## Development

```bash
make setup    # Set up development environment
make format   # Auto-fix and format code (ruff)
make lint     # Check code style and errors (ruff)
make test     # Run all unit tests (pytest)
make build    # Build wheel and sdist into dist/
make clean    # Remove build caches and the virtual environment
```
