Skip to content
← Alle Beiträge
· Delta1 Labs SerilogNebula

Was Umbenennung mit Ihrer Serilog-Ausgabe macht

Obfuszieren Sie eine Anwendung, die mit Serilog protokolliert, und Ihre strukturierten Ereignisse können still von { CustomerName, Total } zu { b, c } werden — aber nur auf einem von zwei Codepfaden. Dieser Beitrag zeigt, warum das Destrukturieren eines Objekts mit {@Order} die lebenden Eigenschaftsnamen spiegelt (die die Umbenennung umschreibt), während das {Order} eines Record und die expliziten Tokens der Nachrichtenvorlage fest eingebrannte Literale sind, die überleben, und grenzt dann Nebula.NET so ein, dass die Protokolle lesbar bleiben, ohne Ihre Logik zu deobfuszieren.

Sie obfuszieren eine Desktop-Anwendung, veröffentlichen sie, und die strukturierten Protokolle, die sie für den Support hochlädt, kommen unleserlich zurück — nicht fehlend, nicht fehlerhaft, nur voller { "b": "Dana Okafor", "c": 49.90 }, wo die letzte Version { "CustomerName": "...", "Total": ... } sagte. Nichts hat eine Ausnahme ausgelöst. Serilog lief genau wie zuvor. Die Namen der Eigenschaften haben sich geändert, weil eine der beiden Arten, wie Sie Serilog ein Objekt übergeben, diese Namen zur Laufzeit liest — und die Umbenennung ist genau das, was sie umschreibt.

Die eigentliche Frage

Serilog sieht nie Ihren Quellcode. Es sieht eine Nachrichtenvorlagen-Zeichenfolge und einige Argumentwerte und verwandelt sie in eine Menge benannter Eigenschaften. Die Frage für einen obfuszierten Build ist also die übliche: Welche Eigenschaftsnamen hat Serilog als literalen Text erfasst, der unverändert in Ihrer Assembly reist, und welche hat es durch Reflexion über lebende Metadaten erfasst, die die Umbenennung umgeschrieben hat? Treffen Sie diese Unterscheidung richtig, bleiben Ihre Protokolle durch die Obfuszierung hindurch lesbar. Treffen Sie sie falsch, benennen sich Ihre strukturierten Ereignisse still selbst um.

Zwei Werte, zwei Codepfade

Nehmen Sie eine triviale Checkout-Protokollierung über einen Record.

public record Order(string CustomerName, decimal Total, int Items);

var order = new Order("Dana Okafor", 49.90m, 3);

Log.Information("Checkout for {Order}", order);   // scalar path
Log.Information("Checkout for {@Order}", order);  // destructure path

Der einzige Unterschied ist das @. Serilog analysiert jede Vorlage und hält für das Token namens Order einen Erfassungshinweis fest: Der erste ist Destructuring.Default (als Skalar behandeln), der zweite ist Destructuring.Destructure. Dieser Hinweis entscheidet den Pfad.

Der Skalarpfad landet im PropertyValueConverter von Serilog bei einem ScalarValue, das aus order.ToString() gebildet wird. Für einen C#-Record wird ToString() vom Compiler generiert, und zwar so, dass der Name jedes Mitglieds als Zeichenfolgenliteral geschrieben wird:

// Order.PrintMembers, decompiled
builder.Append("CustomerName = ");
builder.Append((object)CustomerName);
builder.Append(", Total = ");
builder.Append(Total.ToString());
builder.Append(", Items = ");
builder.Append(Items.ToString());

Diese "CustomerName = "-Zeichenfolgen sind ldstr-Ladevorgänge im #US-Heap. Benennen Sie die Eigenschaft CustomerName in b um, und diese Methode gibt weiterhin CustomerName = … aus, weil der Text zur Kompilierzeit eingefroren wurde und nichts mehr mit dem Metadaten-Namen der Eigenschaft zu tun hat. Die skalare Protokollzeile übersteht die Umbenennung unversehrt.

Der Destrukturierungspfad ruft ToString() nicht auf. Er durchläuft das Objekt:

// Serilog.Capturing — the shape of what destructuring does
var props = type.GetPropertiesRecursive();           // public, readable instance
var members = new List<LogEventProperty>(props.Length);
foreach (var pi in props)
    members.Add(new LogEventProperty(pi.Name, Convert(pi.GetValue(value))));
return new StructureValue(members, type.Name);

Jede erfasste Eigenschaft wird nach pi.Name benannt — dem aktuellen PropertyInfo.Name, jetzt zur Laufzeit gelesen. Nachdem Nebula CustomerName in b und den Typ Order in a umbenannt hat, ist genau das, was die Reflexion zurückgibt, sodass das StructureValue mit den Mitgliedern b, c, d und einer Typ-Kennzeichnung a herauskommt. Ein JSON-Sink schreibt sie als seine Schlüssel. Das Ereignis ist vollständig und korrekt; seine Namen sind verschwunden.

order : OrderCustomerName, Total…{Order} — Skalarpfadruft ToString() / PrintMembers() des RecordNamen sind ldstr-Literale der MethodeCheckout for Order {CustomerName = Dana, Total = 49.90 }{@Order} — Destrukturierungspfadspiegelt GetProperties() zur Laufzeitliest den lebenden (umbenannten) PropertyInfo.NameCheckout for a {b = Dana, c = 49.90 }
Dasselbe Objekt, auf zwei Arten protokolliert. Der Skalarpfad liest in das ToString() des Record eingebrannte Namen; der Destrukturierungspfad liest sie live aus den Metadaten, sodass nur er der Umbenennung folgt.

Nachrichtenvorlagen sind ebenfalls Literale

Die dritte gängige Form umgeht Objekte vollständig:

Log.Information("Checkout for {Customer} total {Total} x{Items}",
    order.CustomerName, order.Total, order.Items);

Die Token-Namen Customer, Total und Items leben in der Vorlagen-Zeichenfolge "Checkout for {Customer} …", die ein einziger ldstr in Ihrer Methode ist. Serilog analysiert dieses Literal zur Laufzeit und paart jedes Token mit einem Positionsargument. Das Umbenennen der Eigenschaften hinter order.CustomerName ändert nichts, was die Vorlage sehen kann — das strukturierte Ereignis hat die Schlüssel Customer, Total, Items, egal wie die zugrunde liegenden Mitglieder heißen. Explizite Vorlagen sind konstruktionsbedingt umbenennungsfest. (Nebula kann die Vorlagen-Zeichenfolge dennoch verschlüsseln; der Wert, den Serilog nach der Entschlüsselung analysiert, ist Byte für Byte das Original, sodass die Token-Namen unverändert bleiben.)

Die Regel ist also klar: Token-Namen und das ToString() eines Record sind Kompilierzeit-Literale und überleben; die {@...}-Destrukturierung spiegelt lebende Namen und folgt der Umbenennung. Dieselbe Teilung erklärt die verwandten Überraschungen — ForContext<T>() setzt SourceContext auf typeof(T).FullName, zur Laufzeit gelesen, und meldet daher den umbenannten Typnamen, und jeder Enricher, der zum Hinzufügen von Eigenschaften über einen Typ spiegelt, liest ebenfalls umbenannte Namen.

Nebula eingrenzen

Wenn Sie strukturierte Protokolle und vollständige Obfuszierung wollen, entscheiden Sie pro Objekt, auf welcher Seite der Teilung es liegt. Die Objekte, die Sie in Protokolle destrukturieren, sind meist schlichte DTOs ohne verbergenswerte Logik, also behalten Sie ihre öffentlichen Mitgliedsnamen und benennen Sie alles andere um. Legen Sie diese Formen in einen einzigen Namespace:

{
  "schemaVersion": 1,
  "inputs": ["bin/Release/net8.0/Checkout.dll"],
  "outputDirectory": "protected",
  "encryptStrings": true,
  "controlFlowObfuscation": true,
  "renaming": {
    "rules": [
      { "pattern": "Checkout.Logging.Shapes.*", "action": "keep", "members": "public" },
      { "pattern": "Checkout.*",                "action": "rename" }
    ]
  }
}
nebula protect --config nebula.config.json

Die erste Regel behält die öffentlichen Eigenschaftsnamen Ihrer Protokollformen bei, damit destrukturierte Ereignisse lesbar bleiben; members: "public" lässt die privaten Felder und Methoden dieser Typen dennoch umbenennen, und die beibehaltenen Typen behalten ihre Kontrollfluss-Obfuszierung und String-Verschlüsselung — Sie geben einige Eigenschaftsnamen auf, nicht den Code dahinter. Alles außerhalb dieses Namespace — Ihre Preisgestaltung, Ihre Lizenzierung, Ihre Domänenlogik — wird in a, b, c umbenannt.

Wenn Sie lieber nichts benannt behalten wollen, gehen Sie den anderen Weg: Protokollieren Sie mit expliziten Vorlagen im sensiblen Code und projizieren Sie Objekte durch eine gewählte Form, statt die echte zu spiegeln.

Log.Logger = new LoggerConfiguration()
    .Destructure.ByTransforming<Order>(o => new { o.Items, Total = o.Total })
    .CreateLogger();

ByTransforming führt Ihr Lambda aus, sodass die Namen der anonymen Form (Items, Total) Literale sind, die der Compiler ausgibt — stabil und unter Ihrer Kontrolle, wobei die Felder, die Sie nicht in den Protokollen haben wollen, einfach weggelassen werden.

Wann es bricht

Drei Ränder sind leiser als der Hauptfall. Erstens das Filtern nach SourceContext: Wenn ein Sink, ein Sub-Logger oder eine Protokollabfrage nach SourceContext routet, passt ein umbenannter Typname aus ForContext<T>() nicht mehr — behalten Sie die Typnamen bei, nach denen Sie filtern, oder setzen Sie den Kontext mit einer expliziten Zeichenfolge: ForContext("SourceContext", "Checkout"). Zweitens ist die quellgenerierte Protokollierung über [LogProperties] oder LoggerMessage das Gegenteil der Destrukturierung: Der Generator brennt den Namen jeder Eigenschaft als Literal zur Kompilierzeit in die generierte Methode ein, sodass diese Namen die Umbenennung genau wie ein Vorlagen-Token überleben — keine Beibehaltungsregel nötig. Drittens die Abdeckung: Die Umbenennung ist unsichtbar, bis ein bestimmtes Ereignis tatsächlich ausgelöst wird, also prüfen Sie die Protokollausgabe des geschützten Builds in einem Smoke-Test, nicht die des Debug-Builds, bevor Sie ihr im Feld vertrauen.

Fazit

Die Obfuszierung bricht Serilog nicht; sie schreibt die einzige Art von Namen um, die Serilog zur Laufzeit liest. Eine {@Order}-Destrukturierung spiegelt über lebende Eigenschaften, sodass die Umbenennung ihre Schlüssel in b und c verwandelt; ein skalares {Order}, das ToString() eines Record und jedes {Token} einer Nachrichtenvorlage sind Kompilierzeit-Literale, die unversehrt durchgehen. Entscheiden Sie, welche Objekte in die Protokolle gehören, behalten Sie nur die öffentlichen Namen dieser Formen bei und lassen Sie Nebula.NET den Rest umbenennen. Öffnen Sie das Ergebnis in Glass.NET, um zu bestätigen, dass sich Ihre Logik als a, b, c liest, während Ihre Protokollformen weiterhin die Namen ausbuchstabieren, die Ihr Support-Team braucht.

Nebula.NET testen

Härten Sie Ihren .NET-Code in wenigen Minuten — starten Sie mit der kostenlosen Edition.