latency-audit 0.1.4
HFT-grade Linux infrastructure validator. Audits kernel, CPU, network, and clock settings against trading latency best practices.
License: MIT
Requires Python: >=3.10
Keywords: audit, devops, hft, high-frequency-trading, infrastructure, latency, linux, performance, sysadmin, trading

# 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
- [x] **UDP socket buffer drops** (RcvbufErrors)
- [x] **NIC hardware discards** (rx_missed_errors)

### Hardware
- [x] **PCIe Link Width & Speed** (validates NICs negotiated at max speed)
- [x] **Memory Channel Balance** (detects asymmetric DIMM population)

### Process
- [x] **Involuntary Context Switches** (scheduler preemption)
- [x] **Major Page Faults** (disk I/O detection)

### 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.3

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                           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
# System-level checks
latency-audit --category kernel
latency-audit --category cpu
latency-audit --category network
latency-audit --category hardware

# Process-specific checks (requires --pid)
latency-audit --category process --pid 1234
```

### Monitor a Running Process

```bash
# Check if your trading application has any scheduler preemptions or disk I/O
latency-audit --category process --pid $(pgrep trading_app)
```

---

## 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>