Metadata-Version: 2.4
Name: latency-audit
Version: 0.1.3
Summary: HFT-grade Linux infrastructure validator. Audits kernel, CPU, network, and clock settings against trading latency best practices.
Project-URL: Homepage, https://github.com/padalan/latency-audit
Project-URL: Documentation, https://github.com/padalan/latency-audit#readme
Project-URL: Repository, https://github.com/padalan/latency-audit.git
Project-URL: Issues, https://github.com/padalan/latency-audit/issues
Project-URL: Changelog, https://github.com/padalan/latency-audit/releases
Author-email: Nikhil Padala <contact@nikhilpadala.com>
License: MIT
License-File: LICENSE
Keywords: audit,devops,hft,high-frequency-trading,infrastructure,latency,linux,performance,sysadmin,trading
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: System Administrators
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
Classifier: Topic :: System :: Benchmark
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# latency-audit

[![PyPI version](https://img.shields.io/pypi/v/latency-audit.svg)](https://pypi.org/project/latency-audit/)
[![Python Versions](https://img.shields.io/pypi/pyversions/latency-audit.svg)](https://pypi.org/project/latency-audit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![CI](https://github.com/padalan/latency-audit/actions/workflows/ci.yml/badge.svg)](https://github.com/padalan/latency-audit/actions)
[![Codecov](https://codecov.io/gh/padalan/latency-audit/branch/main/graph/badge.svg)](https://codecov.io/gh/padalan/latency-audit)

**The HFT Validator.**
A ruthless CLI tool that audits Linux infrastructure against Tier 1 High-Frequency Trading standards.

---

## The Problem

Default Linux kernels are tuned for **throughput** (web servers), not **latency** (trading).

A single misconfigured setting can cost you:

| Misconfiguration | Latency Penalty |
|------------------|-----------------|
| `swappiness > 0` | **+100µs** (page fault) |
| `transparent_hugepages=always` | **+50µs** (compaction stalls) |
| GRO/LRO enabled | **+30µs** per packet |
| Wrong CPU governor | **+200µs** (frequency scaling) |
| C-States enabled | **+500µs** (wake-up latency) |

**In HFT, 1 microsecond = $1M/year.** These defaults are silent killers.

---

## What It Checks

### Kernel
- [x] Swappiness (should be 0)
- [x] Transparent Hugepages (should be `never`)
- [x] Kernel preemption model

### CPU
- [x] Frequency Governor (should be `performance`)
- [x] C-States (should be disabled)
- [x] Core Isolation (`isolcpus` configuration)
- [x] NUMA topology awareness

### Network
- [x] NIC Offloads (GRO/LRO/TSO should be OFF for latency-critical paths)
- [x] IRQ affinity
- [x] Ring buffer sizes

### Clock
- [x] TSC reliability (`constant_tsc`, `nonstop_tsc`)
- [x] Clocksource configuration

---

## Installation

```bash
pip install latency-audit
```

Or install from source for the latest:

```bash
pip install git+https://github.com/padalan/latency-audit.git
```

---

## Usage

### Quick Audit (Read-Only)

```bash
latency-audit
```

Example output:

```
latency-audit v0.1.2

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                           KERNEL CONFIGURATION                            ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
  [PASS] swappiness = 0
  [FAIL] transparent_hugepages = always (should be: never)
  [PASS] kernel.sched_min_granularity_ns = 100000

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                            CPU CONFIGURATION                              ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
  [PASS] governor = performance (all cores)
  [FAIL] C-States enabled (max_cstate = 9, should be: 0)
```

### JSON Output (for CI/CD)

```bash
latency-audit --json
```

```json
{
  "score": 72,
  "checks": [
    {"name": "swappiness", "status": "pass", "value": 0},
    {"name": "thp", "status": "fail", "value": "always", "expected": "never"}
  ]
}
```

### Check Specific Categories

```bash
latency-audit --category kernel
latency-audit --category cpu
latency-audit --category network
```

---

## Security

This tool is **read-only by design**. It:

- Reads `/proc` and `/sys` filesystem
- Reads `sysctl` values
- Inspects NIC settings via `ethtool`
- Never modifies any settings
- Never requires root (though some checks are more complete with it)

---

## Contributing

Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# Clone and install dev dependencies
git clone https://github.com/padalan/latency-audit.git
cd latency-audit
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest
```

---

## Roadmap

- [ ] `--fix` mode with guided remediation
- [ ] Benchmark mode (measure actual latency)
- [ ] Docker container for isolated testing
- [ ] Ansible playbook generation
- [ ] Integration with Prometheus/Grafana

---

## License

MIT © [Nikhil Padala](https://nikhilpadala.com)

---

<p align="center">
  <sub>Built with obsessive attention to microseconds.</sub>
</p>
