Debug-Modus — Sehen Sie genau, was Grepture schwaerzt und wiederherstellt

"Vertrauen Sie uns" reicht nicht

Wenn eine Security-Review fragt "Was macht dieses AI-Gateway eigentlich mit den Daten unserer Kunden?", reicht ein Slack-Screenshot einer Schwaerzungsregel nicht. Auditoren wollen die Anfrage sehen. Kunden wollen die Anfrage sehen. Ehrlich gesagt: Sie wollen die Anfrage selbst sehen — die, die gerade durchgegangen ist, mit den Daten drin, exakt so transformiert, wie sie transformiert wurde.

Das Traffic-Log zeigt bereits den geschwaerzten Body. Das ist die richtige Voreinstellung — nichts Sensitives liegt fuer immer in Ihrem Dashboard. Aber es bedeutet auch: Sie koennen im Nachhinein nicht leicht beweisen, dass die Schwaerzung funktioniert hat. Sie sehen die geschwaerzte Version, nicht den Ausgangspunkt, nicht was tokenisiert wurde gegenueber dem, was permanent entfernt wurde, und nicht, was zurueckkam und auf dem Rueckweg wiederhergestellt wurde.

Deshalb haben wir den Debug-Modus gebaut.

Was erfasst wird

Wenn eine Anfrage den Header X-Grepture-Debug: true (oder die SDK-Option debug: true) enthaelt, erfasst Grepture die komplette Pipeline fuer genau diese eine Anfrage:

Input (roh) — exakt das, was der Aufrufer gesendet hat, bevor irgendetwas veraendert wurde.
Schwaerzungen — jeder PII-Treffer, jede Tokenisierung und jedes Find-Replace, mit Original → Ersatz eins-zu-eins gemappt.
Upstream-Request — der nach der Schwaerzung tatsaechlich an den LLM-Provider gesendete Body.
Upstream-Response — die unveraenderte Antwort des Providers, vor der Detokenisierung.
Finaler Output — was der Aufrufer erhalten hat, mit Mask-and-Restore-Tokens zurueckgetauscht in die Originalwerte.

Im Dashboard erscheint die Anfrage mit einem kleinen lila Bug-Symbol. Das Detail-Sheet bekommt einen Debug-Tab mit einem Diff: Input gegenueber Upstream auf dem Request-Pfad (rot = entfernt, gruen = hinzugefuegt) und Upstream gegenueber Output auf dem Response-Pfad (zeigt, was wiederhergestellt wurde). Eine Schwaerzungs-Tabelle darunter mappt jede Transformation. Die Roh-Bodies aller Stufen sind direkt scrollbar auf derselben Seite.

Das ist der Unterschied zwischen "wir schwaerzen PII" und "hier ist die genaue E-Mail-Adresse, die wir aus dieser Anfrage geschwaerzt haben, hier ist das Token, mit dem wir sie ersetzt haben, hier ist die OpenAI-Antwort, in der das Token vorkam, und hier ist der Output, in dem wir die Adresse wieder eingesetzt haben."

Standardmaessig aus, opt-in pro Anfrage

Der Debug-Modus ist standardmaessig aus. Es gibt keinen Team-Schalter "Debug fuer alle aktivieren" und wir planen keinen. Jede erfasste Spur ist opt-in pro Anfrage — entweder explizit per Header in einem curl-Aufruf oder programmatisch per debug: true in den SDK-Fetch-Optionen.

Das ist Absicht. Die erfasste Zeile enthaelt genau die Pre-Schwaerzungs-Inhalte, die Ihre PII-Regeln eigentlich entfernen sollen. Dieses Material unter den gleichen Bedingungen wie normale Logs aufzubewahren wuerde den Sinn der Regeln untergraben.

24-Stunden-TTL, nie in Cold Storage ausgelagert

Zwei Aufbewahrungs-Eigenschaften, die wichtig sind:

Debug-Spuren loeschen sich nach 24 Stunden automatisch. Jede Zeile traegt einen expires_at-Timestamp 24 Stunden nach Erstellung. Ein geplanter Job laeuft alle 15 Minuten und loescht bedingungslos alles, was diesen Zeitpunkt ueberschritten hat. Die Aufbewahrung ist fest — kein Tarif-Upgrade verlaengert sie, kein Admin-Override, kein "diese eine bitte eine Woche behalten."

Debug-Spuren werden nie in Cold Storage ausgelagert. Normale Traffic-Logs liegen in Postgres fuer das Aufbewahrungsfenster Ihres Tarifs (7/30/90 Tage) und grosse Bodies werden transparent in Cold Storage verschoben. Debug-Spuren bekommen diese Behandlung nicht — sie liegen in einem kurzlebigen Speicher, und wenn der Purge laeuft, sind sie weg. Kein Archiv, keine Backup-Stufe, kein "wir haben eine Kopie behalten, nur fuer den Fall." Nach 24 Stunden existieren sie nirgendwo mehr, wo wir herankaemen.

Strikt blockiert im Zero-Data-Modus

Wenn fuer Ihr Team der Zero-Data-Modus aktiv ist, wird die Debug-Erfassung direkt abgelehnt. Eine Anfrage mit dem Debug-Header erhaelt X-Grepture-Debug: rejected-zero-data in der Antwort und laeuft ohne Erfassung weiter. Der Proxy sieht die Zeile nie.

Zero-Data existiert, damit nichts aufbewahrt wird. Debug existiert, um etwas aufzubewahren. Die beiden schliessen sich strukturell aus, nicht nur durch eine Policy — es gibt keinen Code-Pfad, der eine Debug-Zeile schreibt, wenn Zero-Data an ist.

Wann ihn wirklich verwenden

Drei Faelle, fuer die wir ihn gebaut haben:

Demos — ein Sales-Gespraech, in dem der Interessent die Schwaerzung an eigenen Beispieldaten sehen will. Den Flag fuer eine Anfrage setzen, im Detail-Sheet durch den Diff gehen, am naechsten Morgen ist die Zeile weg.
Audits und Compliance-Reviews — "zeigen Sie mir genau, was dieses System mit PII macht." Eine Debug-Spur ist eine ehrlichere Antwort als ein Screenshot einer Regel.
Regel-Debugging — Sie haben gerade ein neues Find-Replace-Pattern ausgerollt und wollen pruefen, ob es das trifft, was Sie wollten, ohne Ihr ganzes Dev-Setup neu aufzubauen. Eine Anfrage mit Flag, ein Blick in die Schwaerzungs-Tabelle, fertig.

Fuer laufende Observability sind die normalen Traffic-Logs weiterhin das richtige Werkzeug. Sie sind bereits schwaerzungs-sicher und leben das ganze Aufbewahrungsfenster. Der Debug-Modus ist die Lupe — scharf, eng, kurzlebig.

Probieren Sie es aus

Den Header an eine beliebige geproxte Anfrage anhaengen:

curl https://proxy.grepture.com/proxy/v1/chat/completions \
  -H "Authorization: Bearer gr_IHR_KEY" \
  -H "X-Grepture-Target: https://api.openai.com/v1/chat/completions" \
  -H "X-Grepture-Debug: true" \
  -H "Content-Type: application/json" \
  -d '{ "model": "gpt-4o-mini", "messages": [...] }'

Oder aus dem SDK, pro Anfrage oder pro Client:

const res = await grepture.fetch(url, { /* ... */ debug: true });

// Oder fuer jeden Aufruf eines Clients:
const openai = new OpenAI(grepture.clientOptions({
  baseURL: "https://api.openai.com/v1",
  debug: true,
}));

Oeffnen Sie das Traffic-Log, halten Sie nach dem lila Bug-Symbol Ausschau, klicken Sie hinein.

Debug-Modus Referenz — Header, Antwort-Codes, Aufbewahrung, Zero-Data-Verhalten
SDK Debug-Option — Nutzung pro Anfrage und pro Client