Debug-Proto-Repräsentationen deserialisieren

So protokollieren Sie Debugging-Informationen in Protocol Buffers.

Ab Version 30.x werden Protobuf DebugString APIs (Message::DebugString, Message::ShortDebugString, Message::Utf8DebugString), zusätzliche Protobuf APIs (proto2::ShortFormat, proto2::Utf8Format), Abseil-Stringfunktionen (wie absl::StrCat, absl::StrFormat, absl::StrAppend und absl::Substitute) und die Abseil Logging API automatisch Proto-Argumente in ein neues Debugging-Format konvertieren. Sehen Sie die zugehörige Ankündigung hier.

Im Gegensatz zur Protobuf DebugString-Ausgabe formatiert das neue Debugging-Format automatisch sensible Felder, indem es deren Werte durch den String "[REDACTED]" (ohne Anführungszeichen) ersetzt. Um sicherzustellen, dass dieses neue Ausgabeformat nicht von Protobuf TextFormat-Parsers deserialisiert werden kann, unabhängig davon, ob das zugrunde liegende Proto SPII-Felder enthält, fügen wir eine Reihe von zufälligen Links zu diesem Artikel und eine zufällige Leerzeichensequenz hinzu. Das neue Debugging-Format sieht wie folgt aus:

goo.gle/debugstr
spii_field: [REDACTED]
normal_field: "value"

Beachten Sie, dass sich das neue Debugging-Format nur in zwei Punkten vom Ausgabeformat des DebugString-Formats unterscheidet:

  • Das URL-Präfix
  • Die Werte von SPII-Feldern werden durch "[REDACTED]" (ohne Anführungszeichen) ersetzt.

Das neue Debugging-Format entfernt niemals Feldnamen; es ersetzt nur den Wert durch "[REDACTED]", wenn das Feld als sensibel eingestuft wird. Wenn Sie bestimmte Felder in der Ausgabe nicht sehen, liegt das daran, dass diese Felder nicht im Proto gesetzt sind.

Tipp: Wenn Sie nur die URL und nichts anderes sehen, ist Ihr Proto leer!

Warum ist diese URL hier?

Wir möchten sicherstellen, dass niemand menschenlesbare Darstellungen einer Protobuf-Nachricht deserialisiert, die für die Fehlersuche durch Menschen gedacht ist. Historisch gesehen waren .DebugString() und TextFormat austauschbar, und bestehende Systeme verwenden DebugString zum Transport und zur Speicherung von Daten.

Wir möchten sicherstellen, dass sensible Daten nicht versehentlich in Protokollen landen. Daher schwärzen wir transparent einige Feldwerte von Protobuf-Nachrichten, bevor wir sie in einen String umwandeln ("[REDACTED]"). Dies verringert das Risiko von Sicherheits- und Datenschutzverletzungen durch versehentliches Protokollieren, birgt aber das Risiko von Datenverlust, wenn andere Systeme Ihre Nachricht deserialisieren. Um dieses Risiko zu mindern, trennen wir absichtlich das maschinenlesbare TextFormat vom menschenlesbaren Debug-Format für die Verwendung in Protokollnachrichten.

Warum gibt es Links auf meiner Webseite? Warum erzeugt mein Code diese neue "Debug-Darstellung"?

Dies ist beabsichtigt, um die "Debug-Darstellung" Ihrer Pros (z. B. durch Protokollierung erzeugt) inkompatibel mit TextFormat zu machen. Wir möchten verhindern, dass sich jemand auf Debugging-Mechanismen zum Transport von Daten zwischen Programmen verlässt. Historisch wurden das Debug-Format (generiert von den DebugString-APIs) und TextFormat fälschlicherweise austauschbar verwendet. Wir hoffen, dass diese beabsichtigte Anstrengung dies in Zukunft verhindern wird.

Wir haben uns absichtlich für einen Link gegenüber weniger sichtbaren Formatänderungen entschieden, um die Gelegenheit zu erhalten, Kontext zu liefern. Dies kann in Benutzeroberflächen auffallen, z. B. wenn Sie Statusinformationen in einer Tabelle auf einer Webseite anzeigen. Sie können stattdessen TextFormat::PrintToString verwenden, das keine Informationen schwärzt und die Formatierung beibehält. Verwenden Sie diese API jedoch mit Vorsicht – es gibt keine eingebauten Schutzmechanismen. Als Faustregel gilt: Wenn Sie Daten in Debug-Protokolle schreiben oder Statusmeldungen erstellen, sollten Sie weiterhin das Debug-Format mit dem Link verwenden. Selbst wenn Sie derzeit keine sensiblen Daten verarbeiten, bedenken Sie, dass sich Systeme ändern und Code wiederverwendet wird.

Ich habe versucht, diese Nachricht in TextFormat zu konvertieren, aber ich habe festgestellt, dass sich das Format jedes Mal ändert, wenn mein Prozess neu startet.

Dies ist beabsichtigt. Versuchen Sie nicht, die Ausgabe dieses Debug-Formats zu parsen. Wir behalten uns das Recht vor, die Syntax ohne Vorankündigung zu ändern. Die Syntax des Debug-Formats ändert sich pro Prozess zufällig, um versehentliche Abhängigkeiten zu verhindern. Wenn eine syntaktische Änderung im Debug-Format Ihr System beeinträchtigen würde, sollten Sie wahrscheinlich eine TextFormat-API anstelle der Debug-Darstellung eines Pro verwenden.

FAQ

Kann ich einfach überall TextFormat verwenden?

Verwenden Sie TextFormat nicht für die Erstellung von Protokollnachrichten. Dadurch werden alle integrierten Schutzmechanismen umgangen, und Sie riskieren, versehentlich sensible Informationen zu protokollieren. Selbst wenn Ihre Systeme derzeit keine sensiblen Daten verarbeiten, kann sich dies in Zukunft ändern.

Unterscheiden Sie Protokolle von Informationen, die für die weitere Verarbeitung durch andere Systeme bestimmt sind, indem Sie entweder die Debug-Darstellung oder TextFormat entsprechend verwenden.

Ich möchte Konfigurationsdateien schreiben, die sowohl menschenlesbar als auch maschinenlesbar sein müssen

Für diesen Anwendungsfall können Sie explizit TextFormat verwenden. Sie sind dafür verantwortlich, sicherzustellen, dass Ihre Konfigurationsdateien keine PII enthalten.

Ich schreibe einen Unit-Test und möchte den Debugstring in einer Testassertion vergleichen

Wenn Sie Protobuf-Werte vergleichen möchten, verwenden Sie MessageDifferencer wie in folgendem Beispiel:

using google::protobuf::util::MessageDifferencer;
...
MessageDifferencer diff;
...
diff.Compare(foo, bar);

Neben dem Ignorieren von Format- und Feldreihenfolgen erhalten Sie auch bessere Fehlermeldungen.