Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: Python für SRE – llmctl

Ziel: Ein getestetes, gelintetes und installierbares CLI llmctl für Smoke-Tests, Lasttests und Fehlerbudgets bauen · Dauer: ca. 150 min · Voraussetzung: Tag 2

Briefing

  • llmctl chat prüft das Gateway mit einer echten Anfrage, load misst p50/p95/p99 und Fehlerquote, slo rechnet das Fehlerbudget aus Prometheus aus.
  • Nur Standardbibliothek plus httpx; pytest und ruff sind 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())
EOF

Warum? 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")
EOF

Warum? 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.py

Erwartet:

........                                                                 [100%]
8 passed in 0.08s

Achtung: POST auf /v1/chat/completions ist nicht idempotent – jeder Retry kostet Tokens und GPU-Zeit. Darum wenige Retries, und ReadTimeout nach 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
EOF

Warum? 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)
EOF
cat > 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.py

Erwartet:

.........                                                                [100%]
9 passed in 0.07s

Sicherheit: --tenant landet in einer PromQL-Abfrage. Ohne Whitelist-Regex könnte jemand mit x"} 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)
EOF
cat > 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 -q

Erwartet:

.....................                                                    [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()
EOF

Terminal 0:

python3 ~/sre-lab/code/llmctl/examples/fakellm.py

Das 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.0

Terminal 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_URL

Erwartet (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.py

Terminal 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 --version

Erwartet (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 format statt 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)
EOF

Erwartet (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.py

Erwartet (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.py

Erwartet (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 4

Erwartet (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-After respektieren, 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_PROXY wird von httpx gelesen, die CA per SSL_CERT_FILE oder httpx.Client(verify=...).
  • Air-Gap: Wheels samt Abhängigkeiten mit pip download vorab ziehen und beim Kunden pip install --no-index --find-links ./wheels llmctl (Tag 14).
  • Abhängigkeiten pinnen (Lockfile, z. B. uv lock oder pip-tools) und Wheel im CI bauen, scannen und signieren (Tag 13).
  • API-Keys nie als CLI-Argument (sichtbar in ps und Shell-History), sondern aus Umgebung oder Secret-Store (OpenBao Agent, Tag 13).
  • Lasttests beim Kunden nur abgesprochen und mit Limit: Ein load -c 200 gegen eine geteilte GPU ist für andere Mandanten ein Incident.