Tag 3: Python für SRE – llmctl
Ziel: Ein getestetes, gelintetes und installierbares CLI
llmctlfür Smoke-Tests, Lasttests und Fehlerbudgets bauen · Dauer: ca. 150 min · Voraussetzung: Tag 2
Briefing
llmctl chatprüft das Gateway mit einer echten Anfrage,loadmisst p50/p95/p99 und Fehlerquote,slorechnet das Fehlerbudget aus Prometheus aus.- Nur Standardbibliothek plus
httpx;pytestundruffsind Dev-Abhängigkeiten. - Jeder Netzwerkaufruf hat Timeouts, Retries mit Backoff und Jitter
und respektiert
Retry-After. - Tests laufen ohne Netz über
httpx.MockTransport. - Ausgeliefert wird ein Wheel, installiert per
pipx.
llmctl chat|load --Bearer lab-key-acme--> llm-gateway :8080 --> Fake/Ollama :11434
llmctl slo --GET /api/v1/query--> Prometheus :9090 --scrape--> gateway /metrics
Drill 1: Projekt-Skelett mit src-Layout
mkdir -p ~/sre-lab/code/llmctl/{src/llmctl,tests} && cd ~/sre-lab/code/llmctl
cat > pyproject.toml <<'EOF'
[build-system]
requires = ["hatchling>=1.25"]
build-backend = "hatchling.build"
[project]
name = "llmctl"
version = "0.1.0"
description = "SRE-CLI für das llm-gateway (Lab-Code)"
requires-python = ">=3.12"
dependencies = ["httpx>=0.27"]
[project.optional-dependencies]
dev = ["pytest>=8", "ruff>=0.6"]
[project.scripts]
llmctl = "llmctl.cli:main"
[tool.ruff]
line-length = 88
[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP", "S"]
ignore = ["S311"] # random für Jitter ist ok, keine Kryptografie
[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"] # assert ist in pytest erwünscht
[tool.pytest.ini_options]
testpaths = ["tests"]
EOF
cat > src/llmctl/__init__.py <<'EOF'
"""llmctl – SRE-Werkzeug für das llm-gateway."""
__version__ = "0.1.0"
EOF
cat > src/llmctl/__main__.py <<'EOF'
from llmctl.cli import main
raise SystemExit(main())
EOFWarum? Das src-Layout verhindert, dass Tests versehentlich den
Quellordner statt des installierten Pakets importieren.
[project.scripts] erzeugt bei der Installation das Kommando
llmctl.
python3 -m venv .venv && source .venv/bin/activate
pip install -q -e '.[dev]'
python -c 'import llmctl; print(llmctl.__version__)'Erwartet:
0.1.0
Tipp:
-e(editable) verlinkt den Quellcode ins venv. Änderungen wirken sofort, ohne Neuinstallation.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Retries mit Backoff, Jitter und Retry-After
cat > src/llmctl/retry.py <<'EOF'
"""HTTP-Aufrufe mit Retries: exponentielles Backoff, Full Jitter, Retry-After."""
import logging
import random
import time
from collections.abc import Callable
import httpx
log = logging.getLogger(__name__)
RETRY_STATUS = {429, 502, 503, 504}
TIMEOUT = httpx.Timeout(60.0, connect=3.0) # Generierung dauert, Connect nicht
def backoff(attempt: int, base: float = 0.5, cap: float = 8.0) -> float:
"""Full Jitter: zufällig zwischen 0 und min(cap, base * 2**attempt)."""
return random.uniform(0, min(cap, base * 2**attempt))
def retry_after(resp: httpx.Response) -> float | None:
"""Retry-After in Sekunden; HTTP-Datumsangaben ignorieren wir bewusst."""
try:
return max(0.0, float(resp.headers.get("Retry-After", "")))
except ValueError:
return None
def send(
client: httpx.Client,
method: str,
url: str,
*,
retries: int = 3,
sleep: Callable[[float], None] = time.sleep,
**kwargs,
) -> httpx.Response:
for attempt in range(retries + 1):
try:
resp = client.request(method, url, **kwargs)
except httpx.TransportError as exc: # Connect-Fehler, Timeouts
if attempt == retries:
raise
wait, reason = backoff(attempt), type(exc).__name__
else:
if resp.status_code not in RETRY_STATUS or attempt == retries:
return resp
ra = retry_after(resp)
wait = ra if ra is not None else backoff(attempt)
reason = str(resp.status_code)
log.warning(
"retry",
extra={"attempt": attempt + 1, "reason": reason, "sleep_s": round(wait, 3)},
)
sleep(wait)
raise AssertionError("unreachable")
EOFWarum? Ohne Jitter wiederholen alle Clients nach einem Ausfall im
selben Takt (Thundering Herd). Retry-After ist die Ansage
des Servers und hat Vorrang vor dem eigenen Backoff. sleep
ist injizierbar, damit Tests nicht wirklich warten.
cat > tests/test_retry.py <<'EOF'
import httpx
import pytest
from llmctl.retry import backoff, send
def client_with(responses):
"""MockTransport spielt eine feste Folge von Antworten/Fehlern ab."""
calls = iter(responses)
def handler(request: httpx.Request) -> httpx.Response:
item = next(calls)
if isinstance(item, Exception):
raise item
return item
return httpx.Client(base_url="http://gw", transport=httpx.MockTransport(handler))
def test_honors_retry_after():
slept = []
c = client_with(
[
httpx.Response(429, headers={"Retry-After": "2"}),
httpx.Response(200, json={"ok": True}),
]
)
resp = send(c, "POST", "/v1/chat/completions", sleep=slept.append)
assert resp.status_code == 200
assert slept == [2.0]
def test_gives_up_after_retries():
slept = []
c = client_with([httpx.Response(503)] * 3)
resp = send(c, "GET", "/", retries=2, sleep=slept.append)
assert resp.status_code == 503
assert len(slept) == 2
def test_no_retry_on_client_error():
slept = []
c = client_with([httpx.Response(401)])
assert send(c, "GET", "/", sleep=slept.append).status_code == 401
assert slept == []
def test_transport_error_is_retried_then_raised():
slept = []
c = client_with([httpx.ConnectError("refused")] * 2)
with pytest.raises(httpx.ConnectError):
send(c, "GET", "/", retries=1, sleep=slept.append)
assert len(slept) == 1
@pytest.mark.parametrize("attempt,cap", [(0, 0.5), (1, 1.0), (3, 4.0), (10, 8.0)])
def test_backoff_bounds(attempt, cap):
for _ in range(100):
assert 0 <= backoff(attempt) <= cap
EOF
pytest -q tests/test_retry.pyErwartet:
........ [100%]
8 passed in 0.08s
Achtung: POST auf
/v1/chat/completionsist nicht idempotent – jeder Retry kostet Tokens und GPU-Zeit. Darum wenige Retries, undReadTimeoutnach 60 s nur bewusst wiederholen.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Lastgenerator und Fehlerbudget-Logik
cat > src/llmctl/load.py <<'EOF'
"""Lastgenerator: N Anfragen mit begrenzter Parallelität, Latenz-Perzentile."""
import asyncio
import math
import time
from collections import Counter
from dataclasses import dataclass, field
import httpx
@dataclass
class Result:
latencies: list[float] = field(default_factory=list)
codes: Counter = field(default_factory=Counter)
elapsed: float = 0.0
@property
def total(self) -> int:
return sum(self.codes.values())
@property
def errors(self) -> int:
return sum(n for c, n in self.codes.items() if not str(c).startswith("2"))
def summary(self) -> dict:
lat = self.latencies
return {
"requests": self.total,
"errors": self.errors,
"error_rate": round(self.errors / self.total, 4) if self.total else 0.0,
"rps": round(self.total / self.elapsed, 2) if self.elapsed else 0.0,
"p50_s": round(percentile(lat, 50), 3) if lat else None,
"p95_s": round(percentile(lat, 95), 3) if lat else None,
"p99_s": round(percentile(lat, 99), 3) if lat else None,
"codes": {str(k): v for k, v in sorted(self.codes.items(), key=str)},
}
def percentile(values: list[float], p: float) -> float:
"""Nearest-Rank-Methode: kleinster Wert, unter dem p % der Werte liegen."""
if not values or not 0 < p <= 100:
raise ValueError("values leer oder p außerhalb (0, 100]")
ordered = sorted(values)
return ordered[math.ceil(p / 100 * len(ordered)) - 1]
async def run_load(
client: httpx.AsyncClient, payload: dict, total: int, concurrency: int
) -> Result:
result = Result()
sem = asyncio.Semaphore(concurrency)
async def one() -> None:
async with sem:
start = time.perf_counter()
try:
resp = await client.post("/v1/chat/completions", json=payload)
code: int | str = resp.status_code
except httpx.HTTPError as exc:
code = type(exc).__name__
result.latencies.append(time.perf_counter() - start)
result.codes[code] += 1
start = time.perf_counter()
async with asyncio.TaskGroup() as tg:
for _ in range(total):
tg.create_task(one())
result.elapsed = time.perf_counter() - start
return result
EOFWarum? Die Semaphore begrenzt die gleichzeitigen Anfragen (Closed Loop). Nearest-Rank liefert immer einen tatsächlich gemessenen Wert – bei 20 Anfragen ist p99 einfach der langsamste.
SLO 99,5 % über 28 Tage heißt: 0,5 % der Anfragen dürfen 5xx sein. Budget übrig = 1 − Fehlerquote / 0,005.
cat > src/llmctl/slo.py <<'EOF'
"""Fehlerbudget aus Prometheus: Anteil 5xx an allen Gateway-Anfragen."""
import math
import re
import httpx
_TENANT = re.compile(r"^[a-z0-9-]+$")
_WINDOW = re.compile(r"^[0-9]+[smhdwy]$")
def error_ratio_query(window: str, tenant: str | None = None) -> str:
# Eingaben validieren: kein PromQL-Injection über --tenant/--window
if not _WINDOW.match(window):
raise ValueError(f"ungültiges Fenster: {window!r}")
if tenant is not None and not _TENANT.match(tenant):
raise ValueError(f"ungültiger Mandant: {tenant!r}")
sel = f'tenant="{tenant}"' if tenant else 'tenant!="unknown"'
bad = f'sum(increase(gateway_requests_total{{{sel},code=~"5.."}}[{window}]))'
total = f"sum(increase(gateway_requests_total{{{sel}}}[{window}]))"
return f"{bad} / {total}"
def query_scalar(client: httpx.Client, promql: str) -> float | None:
"""Instant Query gegen /api/v1/query; None, wenn es keine Daten gibt."""
resp = client.get("/api/v1/query", params={"query": promql})
resp.raise_for_status()
body = resp.json()
if body.get("status") != "success":
raise RuntimeError(body.get("error", "Prometheus-Fehler"))
result = body["data"]["result"]
if not result:
return None
value = float(result[0]["value"][1])
return None if math.isnan(value) else value
def budget_remaining(error_ratio: float, objective: float) -> float:
"""1.0 = Budget unberührt, 0.0 = aufgebraucht, < 0 = SLO verletzt."""
return 1 - error_ratio / (1 - objective)
EOFcat > tests/test_load.py <<'EOF'
import asyncio
import itertools
import httpx
import pytest
from llmctl.load import percentile, run_load
def test_percentile_nearest_rank():
values = [float(i) for i in range(1, 101)] # 1..100
assert percentile(values, 50) == 50.0
assert percentile(values, 95) == 95.0
assert percentile(values, 99) == 99.0
assert percentile([3.0], 99) == 3.0
def test_percentile_rejects_empty():
with pytest.raises(ValueError):
percentile([], 50)
def test_run_load_counts_errors():
counter = itertools.count()
def handler(request: httpx.Request) -> httpx.Response:
# jede vierte Anfrage scheitert
return httpx.Response(500 if next(counter) % 4 == 3 else 200, json={})
async def go():
async with httpx.AsyncClient(
base_url="http://gw", transport=httpx.MockTransport(handler)
) as client:
return await run_load(client, {}, total=20, concurrency=5)
s = asyncio.run(go()).summary()
assert s["requests"] == 20
assert s["errors"] == 5
assert s["error_rate"] == 0.25
assert s["codes"] == {"200": 15, "500": 5}
EOF
cat > tests/test_slo.py <<'EOF'
import httpx
import pytest
from llmctl.slo import budget_remaining, error_ratio_query, query_scalar
def prom(result):
def handler(request: httpx.Request) -> httpx.Response:
assert request.url.path == "/api/v1/query"
assert "gateway_requests_total" in request.url.params["query"]
data = {"resultType": "vector", "result": result}
return httpx.Response(200, json={"status": "success", "data": data})
return httpx.Client(base_url="http://prom", transport=httpx.MockTransport(handler))
def test_query_contains_tenant_and_window():
q = error_ratio_query("28d", "acme")
assert 'tenant="acme"' in q and "[28d]" in q and 'code=~"5.."' in q
@pytest.mark.parametrize("window,tenant", [("28 d", None), ("28d", 'x"}or vector(1)')])
def test_query_rejects_bad_input(window, tenant):
with pytest.raises(ValueError):
error_ratio_query(window, tenant)
def test_query_scalar():
c = prom([{"metric": {}, "value": [1760000000, "0.001"]}])
assert query_scalar(c, error_ratio_query("28d")) == 0.001
def test_query_scalar_no_data():
assert query_scalar(prom([]), error_ratio_query("28d")) is None
nan = [{"metric": {}, "value": [1760000000, "NaN"]}]
assert query_scalar(prom(nan), error_ratio_query("28d")) is None
def test_budget_remaining():
assert budget_remaining(0.0, 0.995) == pytest.approx(1.0)
assert budget_remaining(0.001, 0.995) == pytest.approx(0.8)
assert budget_remaining(0.01, 0.995) == pytest.approx(-1.0)
EOF
pytest -q tests/test_load.py tests/test_slo.pyErwartet:
......... [100%]
9 passed in 0.07s
Sicherheit:
--tenantlandet in einer PromQL-Abfrage. Ohne Whitelist-Regex könnte jemand mitx"} or vector(1)das Ergebnis fälschen – der zweite Parametertest beweist, dass das abgewiesen wird.
Fortschritt speichern? Kostenlos registrieren
Drill 4: CLI mit argparse und JSON-Logs
cat > src/llmctl/logs.py <<'EOF'
"""Strukturierte Logs: eine JSON-Zeile pro Ereignis auf stderr."""
import json
import logging
import sys
_STD = set(vars(logging.makeLogRecord({}))) | {"message", "asctime"}
class JsonFormatter(logging.Formatter):
def format(self, record: logging.LogRecord) -> str:
data = {
"ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
"level": record.levelname.lower(),
"logger": record.name,
"msg": record.getMessage(),
}
# alles aus extra={...} landet als eigenes Feld im JSON
data |= {k: v for k, v in vars(record).items() if k not in _STD}
return json.dumps(data, default=str)
def setup(verbose: bool = False) -> None:
handler = logging.StreamHandler(sys.stderr)
handler.setFormatter(JsonFormatter())
logging.basicConfig(level=logging.WARNING, handlers=[handler], force=True)
logging.getLogger("llmctl").setLevel(logging.DEBUG if verbose else logging.INFO)
if verbose:
logging.getLogger("httpx").setLevel(logging.INFO)
EOFcat > src/llmctl/cli.py <<'EOF'
"""Einstiegspunkt: llmctl chat | load | slo."""
import argparse
import asyncio
import json
import logging
import os
import sys
import httpx
from llmctl import __version__, logs
from llmctl.load import run_load
from llmctl.retry import TIMEOUT, send
from llmctl.slo import budget_remaining, error_ratio_query, query_scalar
log = logging.getLogger("llmctl")
def positive_int(text: str) -> int:
value = int(text)
if value < 1:
raise argparse.ArgumentTypeError("muss >= 1 sein")
return value
def objective(text: str) -> float:
value = float(text)
if not 0 < value < 1:
raise argparse.ArgumentTypeError("muss zwischen 0 und 1 liegen, z. B. 0.995")
return value
def build_parser() -> argparse.ArgumentParser:
env = os.environ.get
p = argparse.ArgumentParser(prog="llmctl", description="SRE-CLI für llm-gateway")
p.add_argument("--version", action="version", version=f"llmctl {__version__}")
p.add_argument("--url", default=env("LLMCTL_URL", "http://127.0.0.1:8080"))
p.add_argument("--model", default=env("LLMCTL_MODEL", "mistral"))
p.add_argument("-v", "--verbose", action="store_true")
sub = p.add_subparsers(dest="cmd", required=True)
chat = sub.add_parser("chat", help="eine Anfrage über das Gateway")
chat.add_argument("prompt")
chat.add_argument("--max-tokens", type=positive_int, default=256)
chat.add_argument("--retries", type=int, default=3)
load = sub.add_parser("load", help="Lasttest mit Latenz-Perzentilen")
load.add_argument("-n", "--requests", type=positive_int, default=20)
load.add_argument("-c", "--concurrency", type=positive_int, default=5)
load.add_argument("--max-tokens", type=positive_int, default=16)
load.add_argument("--json", action="store_true", help="Ergebnis als JSON")
slo = sub.add_parser("slo", help="Fehlerbudget aus Prometheus")
slo.add_argument("--prometheus", default=env("PROM_URL", "http://127.0.0.1:9090"))
slo.add_argument("--objective", type=objective, default=0.995)
slo.add_argument("--window", default="28d")
slo.add_argument("--tenant")
return p
def payload(args: argparse.Namespace, prompt: str) -> dict:
return {
"model": args.model,
"messages": [{"role": "user", "content": prompt}],
"max_tokens": args.max_tokens,
}
def auth_headers() -> dict[str, str]:
key = os.environ.get("LLMCTL_API_KEY", "")
if not key:
raise SystemExit("LLMCTL_API_KEY ist nicht gesetzt")
return {"Authorization": f"Bearer {key}"} # Key nie loggen
def cmd_chat(args, transport=None) -> int:
with httpx.Client(
base_url=args.url, headers=auth_headers(), timeout=TIMEOUT, transport=transport
) as client:
resp = send(
client,
"POST",
"/v1/chat/completions",
json=payload(args, args.prompt),
retries=args.retries,
)
if resp.status_code != 200:
log.error("chat failed", extra={"status": resp.status_code, "body": resp.text})
return 1
body = resp.json()
print(body["choices"][0]["message"]["content"])
log.info("chat ok", extra={"usage": body.get("usage", {})})
return 0
def cmd_load(args, transport=None) -> int:
async def go():
async with httpx.AsyncClient(
base_url=args.url,
headers=auth_headers(),
timeout=TIMEOUT,
transport=transport,
limits=httpx.Limits(max_connections=args.concurrency),
) as client:
return await run_load(
client, payload(args, "Sag nur: ok"), args.requests, args.concurrency
)
s = asyncio.run(go()).summary()
if args.json:
print(json.dumps(s))
else:
print(
f"requests={s['requests']} errors={s['errors']} "
f"error_rate={s['error_rate']:.1%} rps={s['rps']}"
)
print(f"p50={s['p50_s']}s p95={s['p95_s']}s p99={s['p99_s']}s")
print("codes: " + " ".join(f"{k}={v}" for k, v in s["codes"].items()))
return 1 if s["errors"] else 0
def cmd_slo(args, transport=None) -> int:
promql = error_ratio_query(args.window, args.tenant)
log.debug("promql", extra={"query": promql})
with httpx.Client(
base_url=args.prometheus, timeout=10.0, transport=transport
) as client:
ratio = query_scalar(client, promql)
if ratio is None:
print("keine Daten im Fenster – Gateway gescrapt?")
return 3
left = budget_remaining(ratio, args.objective)
print(
f"SLO {args.objective * 100:g}% über {args.window} "
f"(Mandant: {args.tenant or 'alle'})"
)
print(f"Fehlerquote: {ratio:.3%}")
print(f"Budget erlaubt: {1 - args.objective:.3%}")
print(f"Budget übrig: {left:.1%}")
return 0 if left >= 0 else 2
def main(argv: list[str] | None = None, transport=None) -> int:
args = build_parser().parse_args(argv)
logs.setup(args.verbose)
commands = {"chat": cmd_chat, "load": cmd_load, "slo": cmd_slo}
try:
return commands[args.cmd](args, transport)
except (httpx.HTTPError, ValueError, RuntimeError, KeyError, IndexError) as exc:
log.error("failed", extra={"error": f"{type(exc).__name__}: {exc}"})
return 1
if __name__ == "__main__":
sys.exit(main())
EOF
cat > tests/test_cli.py <<'EOF'
import json
import httpx
import pytest
from llmctl.cli import main
def test_chat_end_to_end(monkeypatch, capsys):
monkeypatch.setenv("LLMCTL_API_KEY", "lab-key-acme")
monkeypatch.delenv("LLMCTL_MODEL", raising=False) # Test hermetisch halten
def handler(request: httpx.Request) -> httpx.Response:
assert request.headers["Authorization"] == "Bearer lab-key-acme"
body = json.loads(request.content)
assert body["model"] == "mistral"
return httpx.Response(
200,
json={
"choices": [{"message": {"content": "Bonjour"}}],
"usage": {"prompt_tokens": 5, "completion_tokens": 2},
},
)
rc = main(["chat", "Hallo"], transport=httpx.MockTransport(handler))
assert rc == 0
assert capsys.readouterr().out.strip() == "Bonjour"
def test_missing_key(monkeypatch):
monkeypatch.delenv("LLMCTL_API_KEY", raising=False)
with pytest.raises(SystemExit, match="LLMCTL_API_KEY"):
main(["chat", "Hallo"])
def test_rejects_zero_concurrency():
with pytest.raises(SystemExit):
main(["load", "-c", "0"])
def test_malformed_response_is_an_error(monkeypatch):
monkeypatch.setenv("LLMCTL_API_KEY", "lab-key-acme")
transport = httpx.MockTransport(lambda request: httpx.Response(200, json={}))
assert main(["chat", "Hallo"], transport=transport) == 1
EOF
pytest -qErwartet:
..................... [100%]
21 passed in 0.06s
Warum? Ergebnis auf stdout, Logs als JSON auf stderr: So kannst du
llmctl load --json | jq pipen, und Loki (Tag 9) kann die
Logs ohne Regex parsen. transport als Parameter macht
main() ohne Netz testbar.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Live gegen das Gateway
Ein echtes Mistral-Modell betreibst du erst ab Tag 5. Bis dahin spielt ein Fake den Modellserver: OpenAI-kompatibel, 50 ms pro Token, Fehlerquote per Umgebungsvariable.
mkdir -p examples
cat > examples/fakellm.py <<'EOF'
"""Fake-Modellserver mit OpenAI-kompatibler API – nur fürs Labor (Tag 3/4)."""
import json
import os
import random
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
HOST = os.environ.get("FAKE_HOST", "127.0.0.1")
PORT = int(os.environ.get("FAKE_PORT", "11434"))
TOKEN_DELAY = float(os.environ.get("FAKE_TOKEN_DELAY", "0.05")) # s pro Token
ERROR_RATE = float(os.environ.get("FAKE_ERROR_RATE", "0")) # Anteil 503
class Handler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1" # Keep-Alive wie bei echten Modellservern
def reply(self, code: int, body: dict) -> None:
data = json.dumps(body).encode()
self.send_response(code)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def do_GET(self) -> None:
if self.path == "/v1/models":
self.reply(200, {"object": "list", "data": [{"id": "mistral"}]})
else:
self.reply(404, {"error": "not found"})
def do_POST(self) -> None:
length = int(self.headers.get("Content-Length", 0))
req = json.loads(self.rfile.read(length) or b"{}")
print(
f"fake: tenant={self.headers.get('X-Tenant')} "
f"auth={self.headers.get('Authorization')}",
flush=True,
)
if self.path != "/v1/chat/completions":
return self.reply(404, {"error": "not found"})
if random.random() < ERROR_RATE:
return self.reply(503, {"error": "fake overload"})
n = int(req.get("max_tokens") or 16)
time.sleep(n * TOKEN_DELAY) # Generierungszeit ~ Anzahl Tokens
prompt = req["messages"][-1]["content"]
p = len(prompt.split())
self.reply(
200,
{
"id": f"fake-{random.randrange(10**6)}",
"object": "chat.completion",
"created": int(time.time()),
"model": req.get("model", "mistral"),
"choices": [
{
"index": 0,
"finish_reason": "length",
"message": {"role": "assistant", "content": f"[fake] {prompt}"},
}
],
"usage": {
"prompt_tokens": p,
"completion_tokens": n,
"total_tokens": p + n,
},
},
)
def log_message(self, fmt: str, *args) -> None:
pass # Zugriffslog aus, die print-Zeile oben reicht
if __name__ == "__main__":
print(f"fake llm on {HOST}:{PORT}", flush=True)
ThreadingHTTPServer((HOST, PORT), Handler).serve_forever()
EOFTerminal 0:
python3 ~/sre-lab/code/llmctl/examples/fakellm.pyDas Gateway baust du erst in Tag 4; heute startest du die fertige
Version aus dem Begleitcode des Buchs (Ordner llm-gateway,
seit Tag 0 in ~/sre-lab/code/llm-gateway). Terminal 1:
cd ~/sre-lab/code/llm-gateway
export UPSTREAM_URL=http://127.0.0.1:11434
TENANT_KEYS="acme:lab-key-acme,globex:lab-key-globex" go run .Erwartet (gekürzt):
{"time":"...","level":"INFO","msg":"listening","addr":":8080",
"upstream":"http://127.0.0.1:11434","tenants":2}
Prometheus schon jetzt starten, damit er alle Anfragen für Drill 6 mitschreibt (Terminal 2):
mkdir -p ~/sre-lab/tag03 && cd ~/sre-lab/tag03
cat > prometheus.yml <<'EOF'
global:
scrape_interval: 5s
scrape_configs:
- job_name: llm-gateway
static_configs:
- targets: ["host.docker.internal:8080"]
EOF
docker run -d --name tag03-prom -p 9090:9090 \
--add-host=host.docker.internal:host-gateway \
-v "$PWD/prometheus.yml:/etc/prometheus/prometheus.yml:ro" \
prom/prometheus:v3.15.0Terminal 2 (lab-key-acme ist ein Lab-Wert):
cd ~/sre-lab/code/llmctl && source .venv/bin/activate
export LLMCTL_API_KEY=lab-key-acme LLMCTL_MODEL=mistral
llmctl chat --max-tokens 20 "Was ist ein Fehlerbudget?"
llmctl load -n 20 -c 2
llmctl load -n 40 -c 20; echo "exit=$?"Erwartet:
{"ts": "2026-10-09T19:03:42", "level": "info", "logger": "llmctl", "msg": "chat ok",
"usage": {"prompt_tokens": 4, "completion_tokens": 20, "total_tokens": 24}}
[fake] Was ist ein Fehlerbudget?
requests=20 errors=0 error_rate=0.0% rps=2.46
p50=0.81s p95=0.815s p99=0.858s
codes: 200=20
requests=40 errors=30 error_rate=75.0% rps=40.3
p50=0.054s p95=0.933s p99=0.936s
codes: 200=10 429=30
exit=1
Warum? Das Gateway erlaubt einen Burst von 10, danach 5 Anfragen/s
pro Mandant. 20 parallele Anfragen leeren den Bucket sofort; die
schnellen 429er drücken p50 nach unten. Darum Perzentile immer zusammen
mit der Fehlerquote lesen. Terminal 0 zeigt
fake: tenant=acme auth=None – der Key erreicht den
Modellserver nie.
Jetzt Retries sehen. Zweites Gateway mit hartem Limit (Terminal 3):
cd ~/sre-lab/code/llm-gateway
LISTEN_ADDR=:8081 RATE_LIMIT_RPS=0.2 RATE_LIMIT_BURST=1 \
TENANT_KEYS="acme:lab-key-acme" go run .Terminal 2:
export LLMCTL_URL=http://127.0.0.1:8081
llmctl chat --max-tokens 5 "Sag ok" 2>/dev/null
llmctl chat --retries 5 --max-tokens 5 "Sag ok"
LLMCTL_URL=http://127.0.0.1:8999 llmctl chat --retries 2 "x"; echo "exit=$?"
unset LLMCTL_URLErwartet (gekürzt):
[fake] Sag ok
{"ts": "...:02", "level": "warning", "logger": "llmctl.retry", "msg": "retry",
"attempt": 1, "reason": "429", "sleep_s": 1.0}
...
{"ts": "...:06", ..., "attempt": 4, "reason": "429", "sleep_s": 1.0}
{"ts": "...:07", "level": "info", "logger": "llmctl", "msg": "chat ok", ...}
[fake] Sag ok
{..., "msg": "retry", "attempt": 1, "reason": "ConnectError", "sleep_s": 0.462}
{..., "msg": "retry", "attempt": 2, "reason": "ConnectError", "sleep_s": 0.812}
{..., "level": "error", "logger": "llmctl", "msg": "failed",
"error": "ConnectError: [Errno 61] Connection refused"}
exit=1
Bei 429 wartet llmctl genau die angesagte Sekunde, bei
Connect-Fehlern zufällig (Jitter). Beende das Gateway in Terminal 3 mit
Ctrl-C.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Fehlerbudget live mit Prometheus
Fehler einbauen: Fake in Terminal 0 beenden (Ctrl-C) und mit 10 % Fehlerquote neu starten.
FAKE_ERROR_RATE=0.1 python3 ~/sre-lab/code/llmctl/examples/fakellm.pyTerminal 2 – zwei Lastwellen mit Pause, dann auswerten:
llmctl load -n 60 -c 3; sleep 10; llmctl load -n 60 -c 3 | head -1
sleep 15
llmctl slo; echo "exit=$?"
llmctl slo --tenant globex; echo "exit=$?"
llmctl slo --objective 0.9 --window 1h; echo "exit=$?"Erwartet (Fehler sind zufällig, deine Werte weichen ab):
requests=60 errors=8 error_rate=13.3% rps=4.02
p50=0.81s p95=0.851s p99=0.971s
codes: 200=52 503=8
requests=60 errors=8 error_rate=13.3% rps=4.03
SLO 99.5% über 28d (Mandant: alle)
Fehlerquote: 4.628%
Budget erlaubt: 0.500%
Budget übrig: -825.6%
exit=2
keine Daten im Fenster – Gateway gescrapt?
exit=3
SLO 90% über 1h (Mandant: alle)
Fehlerquote: 4.657%
Budget erlaubt: 10.000%
Budget übrig: 53.4%
exit=0
Warum ist die Fehlerquote niedriger als die 13 % im Lasttest? Im
Nenner stehen alle Anfragen seit Start, auch die 429er aus Drill 5 – die
zählen hier als „kein Serverfehler”. Und die Serie
code="503" entsteht erst mit dem ersten Fehler: Prometheus
kennt keinen Startwert, increase() zählt nur, was zwischen
zwei Scrapes dazukommt. Ein Teil der ersten Welle fehlt deshalb. In
Produktion initialisiert man solche Counter beim Start mit 0.
Exit-Code 2 bei aufgebrauchtem Budget, 3 ohne Daten: So kann eine
Pipeline vor einem Rollout llmctl slo als Gate nutzen. Mit
-v siehst du die erzeugte PromQL im Debug-Log. Fake danach
wieder ohne Fehlerquote starten.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Lint, Wheel, pipx
cd ~/sre-lab/code/llmctl
ruff check . && ruff format --check .
pip wheel -q --no-deps -w dist .
ls dist
deactivate
pipx install dist/llmctl-0.1.0-py3-none-any.whl
llmctl --versionErwartet (gekürzt):
All checks passed!
12 files already formatted
llmctl-0.1.0-py3-none-any.whl
installed package llmctl 0.1.0, installed using Python 3.12.12
These apps are now available
- llmctl
llmctl 0.1.0
Warum? pipx installiert jedes CLI in ein eigenes venv und legt nur
das Kommando in ~/.local/bin. Das Wheel ist das Artefakt,
das du signierst und verteilst (Tag 13) oder ins Air-Gap-Bundle legst
(Tag 14). Fehlt pipx: brew install pipx bzw.
sudo apt install pipx.
Tipp:
ruff formatstatt Diskussionen über Stil.S-Regeln (Bandit) finden z. B.subprocess(..., shell=True)und hartkodierte Passwörter.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Mistral-SDK gegen La Plateforme und gegen dein Gateway
cd ~/sre-lab/code/llmctl/examples
python3 -m venv ~/sre-lab/tag03/.venv-sdk
PY=~/sre-lab/tag03/.venv-sdk/bin/python
$PY -m pip install -q mistralai && $PY -m pip show mistralai | head -2
cat > sdk_chat.py <<'EOF'
import os
from mistralai.client import Mistral, errors
model = os.environ.get("MISTRAL_MODEL", "mistral-small-latest")
server = os.environ.get("MISTRAL_SERVER_URL") # None = La Plateforme
with Mistral(api_key=os.environ["MISTRAL_API_KEY"], server_url=server) as client:
try:
res = client.chat.complete(
model=model,
messages=[{"role": "user", "content": "Was ist ein SLO? Ein Satz."}],
max_tokens=60,
)
except errors.MistralError as e:
raise SystemExit(f"HTTP {e.status_code}: {e.body}") from None
print(res.choices[0].message.content)
print(res.usage)
EOFErwartet (Version kann abweichen):
Name: mistralai
Version: 3.2.0
Ab Version 2 importierst du aus mistralai.client (v1:
from mistralai import Mistral). Mit echtem Key gegen La
Plateforme (export MISTRAL_API_KEY=..., nie in Code oder
Shell-History):
$PY sdk_chat.pyErwartet (nicht live getestet; gekürzt, kann je nach Version abweichen):
Ein SLO ist ein messbares Ziel für die Zuverlässigkeit eines Dienstes, z. B. ...
prompt_tokens=14 completion_tokens=31 total_tokens=45 ...
Ohne gültigen Key (live getestet):
MISTRAL_API_KEY=ungueltig $PY sdk_chat.py; echo "exit=$?"Erwartet:
HTTP 401: {"detail":"Invalid API Key"}
exit=1
Dasselbe SDK gegen dein Gateway – es spricht dieselbe API:
MISTRAL_API_KEY=lab-key-acme MISTRAL_SERVER_URL=http://127.0.0.1:8080 \
MISTRAL_MODEL=mistral $PY sdk_chat.pyErwartet (gekürzt):
[fake] Was ist ein SLO? Ein Satz.
prompt_tokens=6 completion_tokens=60 total_tokens=66 prompt_audio_seconds=Unset() ...
Warum? So testet ein Kunde seinen bestehenden Mistral-Code gegen eine
On-Prem-Installation: nur server_url und Key tauschen. Das
SDK hat eigene Retries (RetryConfig) – kombiniere sie nicht
ungeprüft mit Retries im Aufrufer, sonst multiplizieren sich die
Versuche.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/sre-lab/code/llmctl
export LLMCTL_API_KEY=lab-key-acme LLMCTL_MODEL=mistral # Lab-Key
check "Tests grün" ".venv/bin/pytest -q"
check "ruff sauber" ".venv/bin/ruff check . && .venv/bin/ruff format --check ."
check "Wheel gebaut" "test -f dist/llmctl-0.1.0-py3-none-any.whl"
check "llmctl per pipx im PATH" "command -v llmctl"
check "chat über Gateway" "llmctl chat --max-tokens 5 'Sag ok'"
check "Lasttest ohne Fehler" "llmctl load -n 5 -c 1"
check "Fehlerbudget lesbar" "llmctl slo | grep -q 'Budget übrig'"Erwartet:
✔ Tests grün
✔ ruff sauber
✔ Wheel gebaut
✔ llmctl per pipx im PATH
✔ chat über Gateway
✔ Lasttest ohne Fehler
✔ Fehlerbudget lesbar
Aufräumen: docker rm -f tag03-prom, Gateway und Fake mit
Ctrl-C beenden.
Challenge
load ist ein Closed-Loop-Test: Wird der Server langsam,
schickt llmctl automatisch weniger Anfragen und beschönigt
p99 (Coordinated Omission). Ergänze --rps, das Anfragen mit
fester Ankunftsrate startet, unabhängig von den Antworten.
Hinweis: Im TaskGroup-Block nach jedem
create_task() kurz schlafen; die Semaphore setzt du dann
mit -c großzügig.
Lösung
In src/llmctl/load.py die Signatur und die Schleife
ändern:
async def run_load(
client: httpx.AsyncClient,
payload: dict,
total: int,
concurrency: int,
rps: float | None = None,
) -> Result:
...
async with asyncio.TaskGroup() as tg:
for _ in range(total):
tg.create_task(one())
if rps: # Open Loop: feste Ankunftsrate, egal wie langsam der Server ist
await asyncio.sleep(1 / rps)In src/llmctl/cli.py das Argument ergänzen und
durchreichen:
load.add_argument("--rps", type=float, help="Open Loop: Anfragen pro Sekunde")
...
return await run_load(
client,
payload(args, "Sag nur: ok"),
args.requests,
args.concurrency,
rps=args.rps,
).venv/bin/pytest -q && .venv/bin/ruff check .
.venv/bin/llmctl load -n 20 -c 20 --rps 4Erwartet (gekürzt):
21 passed in 0.08s
All checks passed!
requests=20 errors=0 error_rate=0.0% rps=3.59
p50=0.806s p95=0.808s p99=0.839s
codes: 200=20
.venv/bin/llmctl nutzt die editierbare Installation; für
die pipx-Version Wheel neu bauen und
pipx install --force dist/llmctl-0.1.0-py3-none-any.whl.
Fortschritt speichern? Kostenlos registrieren
Interview-Notiz
- Frage „Wie machst du Retries richtig?“: exponentielles Backoff mit
Full Jitter,
Retry-Afterrespektieren, nur retryable Codes (429/502/503/504), begrenzte Versuche – bei LLMs zusätzlich Kosten pro Retry im Blick. - p99 statt Durchschnitt: Ein LLM-Endpoint mit 1 s Mittelwert kann 20 s p99 haben (lange Generierungen, Queueing auf der GPU); Latenz immer mit Fehlerquote und Token-Länge zusammen berichten.
- Closed vs. Open Loop und Coordinated Omission in einem Satz erklären können – das unterscheidet Lasttests, die Kapazität messen, von solchen, die sie schönrechnen.
- Fehlerbudget als Entscheidungswerkzeug: Budget übrig → Rollout; Budget weg → Freeze und Reliability-Arbeit.
- Brücke: „Für Vault-Kunden habe ich ähnliche Tools gebaut – Lease-Renewal mit Backoff, Health-Checks gegen HA-Cluster; dieselben Muster gelten für Inference-APIs.”
Enterprise-Notiz
- Firmen-Proxy und eigene CA:
HTTPS_PROXYwird von httpx gelesen, die CA perSSL_CERT_FILEoderhttpx.Client(verify=...). - Air-Gap: Wheels samt Abhängigkeiten mit
pip downloadvorab ziehen und beim Kundenpip install --no-index --find-links ./wheels llmctl(Tag 14). - Abhängigkeiten pinnen (Lockfile, z. B.
uv lockoderpip-tools) und Wheel im CI bauen, scannen und signieren (Tag 13). - API-Keys nie als CLI-Argument (sichtbar in
psund Shell-History), sondern aus Umgebung oder Secret-Store (OpenBao Agent, Tag 13). - Lasttests beim Kunden nur abgesprochen und mit Limit: Ein
load -c 200gegen eine geteilte GPU ist für andere Mandanten ein Incident.