Zum Inhalt springen
Deutsch

Troubleshooting

Wenn in Produktion etwas schiefläuft, ist diese Seite der Startpunkt. Jeder Abschnitt ist ein Symptom, die wahrscheinliche(n) Ursache(n) und was zu prüfen / loggen / messen ist, um die Diagnose zu bestätigen.

Für die Diagnose-Werkzeuge selbst:

Pods starten, erreichen aber nie Up.

Ursachen zum Prüfen (in dieser Reihenfolge):

  1. Seeds unerreichbar — falsche Adressen / DNS / RBAC.
  2. Cluster-Port via Firewall blockiert — Pods können auf 2552 nicht reden.
  3. Unterschiedliche System-Namen — ActorSystem.create('app-a') auf einem Node, 'app-b' auf einem anderen.
  4. TLS-Fehlkonfiguration — Handshake scheitert lautlos.

Diagnostik:

cluster.subscribe((evt) => {
if (evt instanceof MemberJoined) {
system.log.info(`saw join: ${evt.member.address}`);
} else if (evt instanceof SelfUp) {
system.log.info('self up');
}
});

Prüfe, ob SelfUp feuert. Wenn nicht, hat der lokale Node nicht einmal gebootstrappt. Schau dir die Ausgabe des Seed-Providers an:

Terminal-Fenster
kubectl logs pod-1 | grep -i seed
# → "discovered N seeds: ..." ← darf nicht leer sein

Wenn leer: Selector / DNS / Config des Seed-Providers ist falsch.

Mitglieder schwanken zwischen reachable und unreachable.

Ursachen:

  1. Zu enge Failure-Detector-Schwellen für den Jitter des Netzwerks. Siehe Failure-Detector-Tuning.
  2. Netzwerk-Partitionen (echte — diagnostiziere auf Infrastruktur-Ebene). Ohne Downing-Strategie ist eine, die über down-after hinaus anhält, kein Flappen mehr: Jede Seite entfernt die andere und läuft als eigener Cluster weiter. Konfiguriere für Produktion lease-majority oder eine andere Downing-Strategie.
  3. GC-Pausen länger als die Unreachable-Schwelle.

Diagnostik:

rate(cluster_unreachable_duration_ms_count[5m]) > 0.1
# Häufige Übergänge

In Logs:

[INFO ] cluster — node-X marked unreachable
[INFO ] cluster — node-X marked reachable
[INFO ] cluster — node-X marked unreachable

Anhaltendes Flapping signalisiert Schwellen-Tuning.

Nachrichten an eine Sharding-Region erreichen keine Entities.

Ursachen:

  1. Coordinator noch nicht gestartet — Sharding ist asynchron; vor Coordinator-Bereitschaft gesendete Nachrichten werden gepuffert.
  2. Keine Nodes matchen die role — leeres Up-Member-Set, also werden keine Shards allokiert.
  3. Kein hostendes Mitglied ist up — Regionen, die den Typ hosten könnten, sind registriert, aber jede liegt auf einem Mitglied, das unreachable ist (oder noch beitritt), und ein Shard wird nur einem Mitglied zugewiesen, das up ist. Neue Shards warten, bis eines es wieder ist.
  4. extractEntityId liefert undefined — das Message-Routing hat nichts zum Hashen.

Diagnostik:

sharding_shards_hosted{type="entity-type"}
# Sollte numShards (gesamt) clusterweit entsprechen

Logs:

Terminal-Fenster
kubectl logs pod-1 | grep -i shard
# → "coordinator: allocating shard X to node-Y"

Siehst du “no candidates”, lehnt dein role-Filter jeden Node ab. Prüfe Role-Tags in Cluster.join.

Warnt der Koordinator, dass keine der registrierten Regionen, die den Typ hosten können, “is on a member that is up”, dann stimmt die Rolle, und die hostenden Nodes sind das Problem. Er sagt es einmal pro Episode, und die Anfrage bleibt offen, bis ein Mitglied zurückkommt. Unter dem Default wird ein Mitglied, das nicht mehr antwortet, bei down-after entfernt, und seine Shards ziehen zu den Überlebenden um; eines, das als unreachable geparkt ist — von einer Split-Brain-Strategie, die noch nicht entschieden hat, oder unter failure-detector.auto-down = off —, bleibt dort, bis es sich erholt oder etwas es auf down setzt. Prüfe also die Mitgliederliste vor den Sharding-Einstellungen.

Sharding-Metriken zeigen ständige Rebalances; Entities flackern.

Ursachen:

  1. Aggressive Allocation-Strategy — LeastShardAllocationStrategy mit rebalanceThreshold: 1 und häufigen Mitgliedschaftsänderungen.
  2. Flappender Cluster (siehe oben) — ein Mitglied, das immer wieder unreachable wird und zurückkommt, schiebt das Rebalancing auf, statt es auszulösen. Der Koordinator verteilt erst um, wenn die Menge der up-Mitglieder für das Beruhigungsfenster stillgehalten hat (down-after, mit einer Split-Brain-Strategie stable-after); ein kürzeres Flappen verschiebt also keinen Shard, der vorher platziert war. Shards, die während des Flappens zum ersten Mal angefragt werden, landen auf den Mitgliedern, die up sind, und die können übergeben werden, sobald das Mitglied zurück und das Fenster abgelaufen ist — siehe Rebalance. Ein Sturm kommt hier von einer Mitgliedschaft, die sich langsamer als das Fenster ändert — echte Beitritte und Entfernungen, keine kurzen Aussetzer.

Fix:

new LeastShardAllocationStrategy(/* threshold */ 5, /* max */ 3);

Höhere Schwelle = weniger Empfindlichkeit gegenüber kleinen Ungleichgewichten.

preStart braucht lange; das erste onReceive des Actors verzögert sich.

Ursache: tiefes Journal ohne Snapshots. Recovery liest jedes jemals gespeicherte Event.

Diagnostik:

histogram_quantile(0.99, persistence_recovery_duration_ms_bucket)

Wenn P99-Recovery > 1 Sekunde ist, setze eine Snapshot-Policy:

override snapshotPolicy() { return everyNEvents(100); }

Siehe Snapshots.

Symptom: der State einer Entity hängt davon ab, welcher Knoten antwortet

Abschnitt betitelt „Symptom: der State einer Entity hängt davon ab, welcher Knoten antwortet“

State springt nach einem Rebalance oder Deploy zurück; Remembered Entities verschwinden nach einem Coordinator-Failover; eine Projektion verarbeitet Events doppelt.

Ursache: jeder Knoten liest seine eigene Datenbank. Pro-Knoten-Storage (je eine SQLite-Datei, getrennte In-Memory-Stores, zwei Knoten mit je ihrem eigenen Postgres) heißt: eine verschobene Entity replayt, was ihr neuer Knoten gerade hält. Nichts schlägt fehl — der optimistische Append-Check läuft gegen die lokale Datenbank und kann über Knoten hinweg strukturell nicht feuern.

Diagnose — zwei Log-Nadeln, beide einmal pro Knoten:

node-local storage # der Store kann nie geteilt sein (#1356)
storage identity differs # teilbar, aber zwei Instanzen (#1358)

Die zweite fängt auch Fehlkonfiguration, die man dem Backend-Namen nicht ansieht: veraltete Connection-Strings, ein zurückgespieltes Backup, zwei „identische” Datenbank-Container.

Fix: alle Knoten auf dieselbe Datenbank-Instanz zeigen lassen — siehe Storage-Lokalität & Identität — oder Replicated Event Sourcing nutzen, wo Pro-Knoten-Journale das gewollte Design sind. Für bereits divergierte Historien gibt es keine automatische Reparatur: pro Persistence-Id die überlebende Datenbank wählen, die anderen daraus neu befüllen (migrateBetweenJournals) und die Verdrahtung vor dem Neustart fixen.

Symptom: Events wiederhergestellt, aber State ist falsch

Abschnitt betitelt „Symptom: Events wiederhergestellt, aber State ist falsch“

Nach Restart entspricht der State des Actors nicht dem, was er laut Journal sein sollte.

Ursachen:

  1. onEvent hat einen Seiteneffekt — läuft während des Replays und verändert irgendwie den State-Pfad.
  2. onEvent nutzt Date.now() oder Zufall — nicht-deterministisch; jeder Replay produziert anderen State.
  3. Schema-Änderung ohne Adapter — alte Events haben eine andere Form als onEvent erwartet.

Diagnostik: Vergleiche den State des Actors nach Recovery mit dem Inhalt des Journals. Replaye manuell in einem Test, um die Ursache zu isolieren.

Symptom: das Journal ist weg und die Actors antworten einfach nicht mehr

Abschnitt betitelt „Symptom: das Journal ist weg und die Actors antworten einfach nicht mehr“

Kein Fehler, kein Restart, keine Dead Letters. Persistente Actors nehmen Kommandos an und antworten nie; der Heap wächst; die einzige Logzeile ist mailbox high-water mark bei 10 000 und danach bei jeder Verdopplung.

Ursache: ein append, das weder gelingt noch scheitert. Ein Backend, das Verbindungen ablehnt, scheitert von selbst schnell. Eines, das die Verbindung annimmt und dann hängt — ein umgeschwenktes Primary, das den Socket noch hält, ein ausgelasteter Connection Pool, ein Netzpfad, der Pakete verschluckt —, lässt await this.persist(...) für immer offen. Der Turn des Actors endet nie, seine Kommandos stauen sich in der standardmäßig unbegrenzten Mailbox, nichts wirft, und die Supervision läuft nie.

Abhilfe: dem Append eine Frist geben. Das Journal wird durch einen Circuit Breaker gerufen, und dessen Per-Call-Timeout ist das, was einen einzelnen Append begrenzt. Das gilt für jeden Journal-Aufruf eines PersistentActor und für das eigene persist und die Recovery eines ReplicatedEventSourcedActor — aber noch nicht für dessen Anhängen eines Events, das ein Peer geschickt hat; das wartet auf #958. Es wird ungesetzt ausgeliefert, weil genau das Weglassen „keine Frist“ ausdrückt:

actor-ts.circuit-breaker.persistence-journal.call-timeout = 10s

Damit taucht der Hänger als CircuitBreakerTimeoutError auf, der aus dem eigenen onCommand fliegt — beim Hänger und ihn benennend —, und nach max-failures davon (standardmäßig 10) öffnet der Breaker: Jedes weitere persist scheitert sofort mit CircuitBreakerOpenError, bis reset-timeout (15 s) eine Probe durchlässt. Wähle das Timeout nach der P99-Schreiblatenz des Backends plus Reserve, nicht danach, wie lange du warten magst. Bei aktivierten Metriken wird dieses P99 für dich gemessen, am Breaker:

histogram_quantile(0.99, sum by (le) (rate(persistence_journal_latency_seconds_bucket{operation="append"}[5m])))

Ist das Timeout gesetzt, unterscheiden dieselben Familien die Fehler: ein steigendes persistence_journal_failures_total{reason="timeout"} ist der Hänger, der abgeschnitten wird, und persistence_breaker_state{breaker="journal"} == 2 ist der Breaker, der jedes Append abweist. Ein Aufruf, der nie zurückkehrt, wird nie gemessen — solange kein call-timeout existiert, taucht der Hänger selbst also nicht im Histogramm auf, nur als die Appends, die dort nicht mehr ankommen. Siehe Persistenz-Metriken.

Das Timeout gibt auf, statt abzubrechen — ein Schreibvorgang, der die Frist gerissen hat, kann also trotzdem landen. Das ist sicher: Der Wurf überspringt die State-Faltung und lässt lastSequenceNr unberührt, der Restart liest also den echten Kopf. Ein nicht wiederholbarer Seiteneffekt im Handler ist allerdings schon gelaufen. Ein ReplicatedEventSourcedActor ist die Ausnahme: Ein Schreibvorgang, der in das Timeout lief und trotzdem landet, wird nie live gefaltet und erreicht die Peers nie, denn nur ein erfolgreiches persist faltet und verteilt. Eine spätere Recovery faltet ihn nur, wenn sie ihn wieder abspielt — ein nach der Landung aufgenommener Snapshot zählt das Event als abgedeckt, also faltet eine Recovery aus diesem Snapshot es nie, ein vollständiges Replay dagegen schon — siehe Replicated Event Sourcing.

Verwandte Stellschrauben im selben Block:

  • actor-ts.persistence.recovery-timeout (30s) macht dasselbe für eine Recovery, die nie fertig wird: danach scheitert ein PersistentActor mit einem RecoveryTimeoutError über onRecoveryFailure, und ein ReplicatedEventSourcedActor — der keinen solchen Hook hat — lässt damit sein preStart scheitern, statt in preStart zu verharren.
  • actor-ts.persistence.max-concurrent-recoveries (50) verhindert, dass ein Restart-Sturm Tausende gleichzeitiger Reads gegen einen Pool für Dutzende öffnet.
  • actor-ts.persistence.snapshot-is-optional lässt einen Actor per vollständigem Journal-Replay hochkommen, wenn nur der Snapshot Store weg ist. Für einen Actor mit integrity() oder encryption() gilt es nicht — siehe PersistentActor.

Ein JournalConcurrencyError zählt nie auf max-failures ein, ein Schwall verlorener bedingter Appends kann den Breaker also nicht für alle öffnen. Öffnet ein Breaker wegen etwas anderem, das du für harmlos hältst, benenne es, statt das Budget zu erhöhen:

actor-ts.circuit-breaker.persistence-journal.ignored-error-names = ["MyTransientError"]

Heap wächst linear mit Uptime; irgendwann OOM.

Ursachen (häufigste zuerst):

  1. Eine Mailbox mit langsamem Consumer — Mailboxes sind per Default unbounded, ein Producer, der seinen Consumer überholt, lässt also den Heap wachsen, bis einer von beiden aufgibt. actor_mailbox_size zeigt welcher Actor, und ab 10 000 Nachrichten steht eine Backlog-Warnung im Log.
  2. Subscriber-Set-Leaks — Actors registrieren sich am Event-Stream oder DistributedPubSub, aber unsubscriben sich beim Stop nicht.
  3. DistributedData-Keys sammeln sich — LWWMap mit Millionen Keys.
  4. Persistente Puffer — Stash-Puffer, Ask-Reply-To-Refs.

Diagnostik:

actor_mailbox_size{class=...}
# Finde Actors mit dauerhaft großen Queues
histogram_quantile(0.99, rate(actor_mailbox_wait_seconds_bucket[5m]))
# …und wie lange Nachrichten warten, bis jemand sie annimmt.
# Eine Serie entsteht erst ab 10 000 wartenden Nachrichten — dies
# ist also das Signal, das sich zuerst bewegt: ein Rückstau zeigt
# sich als Wartezeit, lange bevor er sich als Größe zeigt.
histogram_quantile(0.99, rate(actor_mailbox_depth_bucket[5m]))
# Wie tief die Queues tatsächlich wurden. Anders als das Gauge hat
# dies keine Untergrenze — ein Ausschlag von einigen Tausend zeigt
# sich hier und nirgends sonst. Und anders als das Gauge ist es eine
# Verteilung: ein Ausschlag zwischen zwei 2-Sekunden-Samples wird
# trotzdem festgehalten.
histogram_quantile(0.99,
rate(actor_dispatcher_queue_delay_seconds_bucket[5m]))
# Eine Ebene höher: Züge, die auf den Dispatcher warten, statt
# Nachrichten, die auf den Actor warten. Hoch hier und niedrig oben
# heißt, die Actors sind in Ordnung und das Scheduling ist die Queue.
Terminal-Fenster
# Heap-Dump über Runtime-Tools:
node --inspect / Buns Profiler

Prüfe Mailbox-Sizing + die Leak-Muster in Event-Stream.

Actor-Arbeit ist okay; HTTP-Antworten sind langsam.

Ursache: Ein Actor monopolisiert die Event Loop und hungert HTTP-Handler aus.

Fix: Per-Actor ThroughputDispatcher auf den schweren Actor.

Bun- / Vitest-Testprozess beendet sich nicht.

Ursache: await system.terminate() wurde im Fixture-Teardown nicht aufgerufen. Geleakte Scheduler / Actor-Cells halten die Event Loop am Leben.

Fix:

afterEach(async () => {
await tk.shutdown();
});

Siehe TestKit.

Ein tell kehrte normal zurück, der Empfänger hat sie nie verarbeitet, und nichts hat geworfen.

tell ist Fire-and-Forget: Es kann weder einen gestoppten Empfänger melden noch eine Selection, die ins Leere lief, noch ein Behavior, das mit unhandled geantwortet hat. Jeder dieser Fälle wird zu einem Dead Letter, und seit #1000 sagt ein Standardsystem das im Log:

[…] INFO dead letter to actor-ts://app/user/worker: OrderPlaced from actor-ts://app/user/api

Suche im Log nach dead letter to und lies den Empfängerpfad — das ist der Actor, den die Nachricht nicht erreicht hat, nicht das Dead-Letter-Büro. Drei Dinge, bevor du auf „es war nur eine“ schließt:

  • Der Eintrag ist gedrosselt. Nach zehn Letters meldet eine einzelne warn-Zeile, dass das Logging für fünf Minuten aussetzt; eine zweite nennt die Bilanz beim Wiederaufnehmen. Erhöhe actor-ts.diagnostics.log-dead-letters oder setze actor-ts.diagnostics.log-dead-letters-suspend-duration = 0, um während der Suche jedes einzelne zu loggen.
  • Die Payload steht nicht im Log, nur die Klasse der Nachricht — das ist Absicht. Um die Nachricht selbst zu sehen, abonniere DeadLetter auf dem Event-Stream oder schalte die Queue mit actor-ts.dead-letters.store = "memory" ein und lies sie mit system.deadLetterQueue.list() zurück.
  • Der Shutdown ist standardmäßig still. Wenn die Nachricht während terminate() verloren ging, siehe das nächste Symptom.

Siehe Dead Letters.

Arbeit, die beim Aufruf von terminate() in der Queue stand, lief nie und taucht stattdessen im Dead-Letter-Stream auf.

terminate() leert zuerst die Actors unter /user, ein einfacher Rückstau wird also verarbeitet. Auf vier Dinge wartet es nicht:

  • Das Drain-Budget ist abgelaufen. Es ist actor-ts.system.shutdown-drain-timeout, Default 2 s. Ein Actor, der beim Leeren immer neue Arbeit erzeugt — eine Self-Tell-Schleife, ein Ballwechsel zwischen zwei Actors — wird nie ruhig, nur das Budget beendet ihn. Erhöhe das Budget, und mit ihm actor-ts.coordinated-shutdown.default-phase-timeout, wenn du über die Pipeline herunterfährst.
  • Die Mailbox war geparkt. context.throttle(...) und eine vom Supervisor suspendierte Mailbox gelten beide als ruhig, weil keine von beiden sich in einem Tempo leert, auf das ein Shutdown warten kann. Brich den Throttle vor dem Herunterfahren ab, wenn der Rückstau zählt.
  • Die Arbeit lag noch in keiner Mailbox. Ein noch nicht gefeuerter context.timers-Tick oder ein tell aus einem Promise, das ein Handler ohne await gestartet hat, kommt an, nachdem der Baum ruhig aussieht. Awaite es oder schicke es stattdessen als Nachricht.
  • Sie war an /system adressiert. Framework-Actors sind konstruktionsbedingt nie ruhig und daher nicht Teil des Drains.

Um herauszufinden, welcher Fall vorliegt, abonniere vor dem Herunterfahren DeadLetter auf dem Event-Stream — der Dead Letter nennt Nachricht und Empfänger. Das Abonnieren muss vorher passieren, denn standardmäßig bewahrt nichts ein Dead Letter auf, es gibt also nachträglich nichts nachzulesen. Das Log hilft hier auch nicht: Genau dieser Schwall ist der eine Fall, der nicht geloggt wird, weil ein geordnetes Herunterfahren ihn jedes Mal erzeugt (setze actor-ts.diagnostics.log-dead-letters-during-shutdown = on, wenn du ihn trotzdem willst). Setze actor-ts.dead-letters.store = "persistent", wenn du die Aufzeichnung lieber hättest, ohne vorher zu wissen, dass du sie brauchen wirst — siehe Dead Letters.

Tests sind lokal grün, fallen aber in CI um.

Die übliche Ursache ist Real-Clock-Timing: ein fester Sleep, der auf einer unbeschäftigten Maschine lang genug ist und auf einem ausgelasteten CI-Runner zu kurz. Nutze ManualScheduler, um Zeit deterministisch zu steuern, oder warte auf den beobachtbaren Zustand statt auf eine Dauer.

Das ist nicht die einzige Ursache, und zwischen ihnen zu raten kostet einen Nachmittag. Test-Flakes diagnostizieren hat das Repeat-Run-Harness, das einen Flake von einem kaputten Test trennt, dazu die katalogisierten Ursachen — ein Timer-Quantum, das zu früh feuert, ein Dispatcher-Hop, den kein Poll-Intervall gewinnt, und die drei Multi-Node-Suites, die CI gar nicht ausführt.

1. Logs auf ERROR-Level-Einträge prüfen. Nach Zeitfenster um das
Problem filtern.
2. Stock-Metriken prüfen — was hat sich verändert? (Restart-Rate,
Mailbox-Tiefe, Member-Anzahl).
3. Cluster-Events am Event-Stream prüfen.
4. Wenn ein Request scheitert, der Trace-ID durch Logs / Trace-Backend
folgen.
5. Wenn möglich, in einem Multi-Node-Spec-Test reproduzieren.

Das Framework ist standardmäßig still und bleibt es, bis du fragst. Vier Schalter unter actor-ts.diagnostics schalten ein, was es über sich selbst sagen kann:

actor-ts {
logger.level = debug # the second switch — see below
diagnostics {
log-config-on-start = on # one info record: every key, and which layer set it
debug {
unhandled = on # a message an actor was handed and declined
lifecycle = on # actor start, stop, restart
event-stream = on # subscribe / unsubscribe, never publish
}
}
}

log-config-on-start ist der erste Griff, wenn eine Einstellung nicht das tut, was du geschrieben hast. Es schreibt den zusammengeführten Baum — jeden Key, sortiert, jeweils mit der Schicht, die gewonnen hat (reference, project-reference, application, profile, secrets oder override), ob sie eine tiefere verdrängt hat und aus welchen Umgebungsvariablen sein Wert stammt. So sehen „meine application.conf wird ignoriert“ und „meine application.conf sagt etwas anderes“ nicht länger gleich aus. reference ist die mit actor-ts gebündelte reference.conf, project-reference die eigene deines Projekts samt ihrem aktiven Profil, profile der Block des aktiven Profils in der Anwendungsdatei, secrets die Secrets-Datei samt ihrem eigenen aktiven Profil, und override das, was dein Code übergeben hat. Die Kopfzeile nennt das aktive Profil und die vier Dateien, nach denen gesucht wurde — die reference.conf des Projekts, die application.conf, die Secrets-Datei und die .env-Datei —, und sagt, wenn eine davon fehlte — was den ersten Fall schon allein klärt. Ein Key, der einen Punkt enthält — etwa ein Hostname —, steht in doppelten Anführungszeichen, so wie HOCON ihn schreibt: webhooks."hooks.example.com" ist ein Key, webhooks.hooks.example.com wären vier. Ein Ausschnitt, mit aktivem production:

actor-ts.diagnostics.log-config-on-start = "on" [application, overrides a lower layer]
actor-ts.diagnostics.log-dead-letters = 10 [reference]
my-app.auth-header = <redacted> [application]
my-app.db.dsn = <redacted> [application, from $DB_PASSWORD]
my-app.db.host = "db.internal" [profile, overrides a lower layer]
my-app.db.password = <redacted> [secrets]
my-app.db.pool-size = 8 [project-reference]
my-app.db.user = <redacted> [override, overrides a lower layer]
my-app.payments.api-key = <redacted> [application]
my-app.upstreams = [{"host":"db-1","password":"<redacted>"}] [application]

Zwei Dinge, bevor du diesen Eintrag in ein Ticket kopierst. Es ist ein info-Eintrag, braucht also keinen zweiten Schalter — aber er druckt deine Konfiguration, und vier Regeln entscheiden, was er zurückhält. Ein Wert wird zurückgehalten, wenn irgendein ganzes Wort seines Key-Namens — des Keys selbst oder eines Zweigs darüber, egal an welcher Stelle im Namen das Wort steht — password, passphrase, passwd, pass, secret, token, key, credential, auth oder authorization lautet, im Singular wie im Plural, und der Wert kein Boolean ist: der auth-header und der api-key oben. Ein Name wird an jedem Zeichen, das weder Buchstabe noch Ziffer ist, an jedem camelCase-Höcker und vor einer Ziffer nach einem Buchstaben in Wörter zerlegt, also enthält apiKey das Wort key, password2 das Wort, das es nummeriert, und passivation-idle kein pass. An ein anderes Wort geklebt (pgpassword, clientsecret, ghtoken) zählen diese Wörter auch, bis auf key, pass und auth, auf die gewöhnliche Wörter enden; von den Namen auf …key zählen apikey, accesskey, secretkey und privatekey, und pwd zählt neben einem anderen Wort des Key-Pfads, wie in mysql-pwd oder db.pwd — nur eine Variable, die bloß PWD heißt, das Arbeitsverzeichnis einer Shell, nicht. Ein Wert, den eine Umgebungsvariable geliefert hat, wird zurückgehalten, wenn ihr Name nach derselben Regel Zugangsdaten benennt, egal wie sein Key heißt: der dsn oben, gebaut aus ${DB_PASSWORD} aus einer .env-Datei, und jeder Wert, der auf ihn verweist. Jeder Wert, den die Secrets-Datei setzt, wird zurückgehalten, egal wie sein Key heißt — auch nachdem eine höhere Schicht den Key überschrieben hat, wie beim user oben. Beides gilt auch im Dump eines WorkerMesh-Workers. Und eine Liste ist ein einziger Key, also werden die Objekte darin Feld für Feld nach der ersten Regel gelesen: ihr password erscheint als "<redacted>", der Rest der Liste wie geschrieben. Nach dem Wert maskiert wird allein die Userinfo einer URL: redis://default:s3cret@redis.example:6379 erscheint unter jedem Key als redis://***@redis.example:6379, dsn und connection-string eingeschlossen. Jedes andere Geheimnis außerhalb der Secrets-Datei, unter einem Key und aus einer Variable, die keines benennen, steht vollständig da — ein ausgeschrieben nacktes Passwort in einem dsn, ein ?password= oder ?authToken= im Query-String, die Form Server=…;Password=… von SQL Server und die schemalose Server-Liste user:password@host von Memcached. Gewöhnliche Tuning-Werte werden nicht zurückgehalten, bloß weil sie eines dieser Wörter in einem längeren Wort buchstabieren — passivation-idle und keyspace werden gedruckt, und das müssen sie auch, damit der Dump lesenswert bleibt. Einer, der ein solches Wort als ganzes enthält, wird mit zurückgehalten: eine eigene token-bucket-size erscheint als <redacted>, und nur die Keys, die reference.conf mitbringt, etwa cache.redis.key-prefix, sind namentlich ausgenommen. Konfiguration nennt die Grenzen vollständig.

Die drei debug.*-Schalter brauchen zwei Schalter, und das ist der übliche Grund, warum einer davon scheinbar nicht wirkt: Der Key entscheidet, ob ein Eintrag entsteht, logger.level = debug entscheidet, ob er geschrieben wird. Jeder steht auf aus, weil jeder ein Eintrag pro Ereignis auf einem Pfad ist, den deine Anwendung treibt — pro abgelehnter Nachricht, pro Actor-Übergang, pro Subscription. Schalte also den ein, der zum Symptom passt, nicht alle drei.

  • Operations-Überblick — die breitere Produktions-Checkliste.
  • FAQ — häufige Fragen und Stolperfallen.
  • Stock-Metriken — was zu lesen ist, wenn Symptome auftauchen.
  • Logging — wie Logs tatsächlich nützlich werden.
  • Tracing — Per-Request-Flow, wenn Logs nicht reichen.