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:
- Logging — strukturierte Logs.
- Stock-Metriken — eingebaute Actor- / Cluster-Metriken.
- Tracing — Per-Request-Flow.
Cluster
Abschnitt betitelt „Cluster“Symptom: Cluster bildet sich nicht
Abschnitt betitelt „Symptom: Cluster bildet sich nicht“Pods starten, erreichen aber nie Up.
Ursachen zum Prüfen (in dieser Reihenfolge):
- Seeds unerreichbar — falsche Adressen / DNS / RBAC.
- Cluster-Port via Firewall blockiert — Pods können auf 2552 nicht reden.
- Unterschiedliche System-Namen —
ActorSystem.create('app-a')auf einem Node,'app-b'auf einem anderen. - 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:
kubectl logs pod-1 | grep -i seed# → "discovered N seeds: ..." ← darf nicht leer seinWenn leer: Selector / DNS / Config des Seed-Providers ist falsch.
Symptom: Cluster flappt
Abschnitt betitelt „Symptom: Cluster flappt“Mitglieder schwanken zwischen reachable und unreachable.
Ursachen:
- Zu enge Failure-Detector-Schwellen für den Jitter des Netzwerks. Siehe Failure-Detector-Tuning.
- Netzwerk-Partitionen (echte — diagnostiziere auf
Infrastruktur-Ebene). Ohne Downing-Strategie ist eine, die über
down-afterhinaus anhält, kein Flappen mehr: Jede Seite entfernt die andere und läuft als eigener Cluster weiter. Konfiguriere für Produktionlease-majorityoder eine andere Downing-Strategie. - GC-Pausen länger als die Unreachable-Schwelle.
Diagnostik:
rate(cluster_unreachable_duration_ms_count[5m]) > 0.1# Häufige ÜbergängeIn Logs:
[INFO ] cluster — node-X marked unreachable[INFO ] cluster — node-X marked reachable[INFO ] cluster — node-X marked unreachableAnhaltendes Flapping signalisiert Schwellen-Tuning.
Sharding
Abschnitt betitelt „Sharding“Symptom: Sharded Entities spawnen nicht
Abschnitt betitelt „Symptom: Sharded Entities spawnen nicht“Nachrichten an eine Sharding-Region erreichen keine Entities.
Ursachen:
- Coordinator noch nicht gestartet — Sharding ist asynchron; vor Coordinator-Bereitschaft gesendete Nachrichten werden gepuffert.
- Keine Nodes matchen die
role— leeres Up-Member-Set, also werden keine Shards allokiert. - Kein hostendes Mitglied ist
up— Regionen, die den Typ hosten könnten, sind registriert, aber jede liegt auf einem Mitglied, dasunreachableist (oder noch beitritt), und ein Shard wird nur einem Mitglied zugewiesen, dasupist. Neue Shards warten, bis eines es wieder ist. - extractEntityId liefert undefined — das Message-Routing hat nichts zum Hashen.
Diagnostik:
sharding_shards_hosted{type="entity-type"}# Sollte numShards (gesamt) clusterweit entsprechenLogs:
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.
Symptom: Rebalance-Storm
Abschnitt betitelt „Symptom: Rebalance-Storm“Sharding-Metriken zeigen ständige Rebalances; Entities flackern.
Ursachen:
- Aggressive Allocation-Strategy —
LeastShardAllocationStrategymitrebalanceThreshold: 1und häufigen Mitgliedschaftsänderungen. - Flappender Cluster (siehe oben) — ein Mitglied, das immer
wieder
unreachablewird und zurückkommt, schiebt das Rebalancing auf, statt es auszulösen. Der Koordinator verteilt erst um, wenn die Menge derup-Mitglieder für das Beruhigungsfenster stillgehalten hat (down-after, mit einer Split-Brain-Strategiestable-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, dieupsind, 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.
Persistence
Abschnitt betitelt „Persistence“Symptom: Actor braucht 30 Sekunden zum Starten
Abschnitt betitelt „Symptom: Actor braucht 30 Sekunden zum Starten“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:
onEventhat einen Seiteneffekt — läuft während des Replays und verändert irgendwie den State-Pfad.onEventnutztDate.now()oder Zufall — nicht-deterministisch; jeder Replay produziert anderen State.- Schema-Änderung ohne Adapter — alte Events haben eine andere
Form als
onEventerwartet.
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 = 10sDamit 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 einPersistentActormit einemRecoveryTimeoutErrorüberonRecoveryFailure, und einReplicatedEventSourcedActor— der keinen solchen Hook hat — lässt damit seinpreStartscheitern, statt inpreStartzu 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-optionallässt einen Actor per vollständigem Journal-Replay hochkommen, wenn nur der Snapshot Store weg ist. Für einen Actor mitintegrity()oderencryption()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"]Speicher + Performance
Abschnitt betitelt „Speicher + Performance“Symptom: Speicher wächst unbegrenzt
Abschnitt betitelt „Symptom: Speicher wächst unbegrenzt“Heap wächst linear mit Uptime; irgendwann OOM.
Ursachen (häufigste zuerst):
- 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_sizezeigt welcher Actor, und ab 10 000 Nachrichten steht eine Backlog-Warnung im Log. - Subscriber-Set-Leaks — Actors registrieren sich am Event-Stream oder DistributedPubSub, aber unsubscriben sich beim Stop nicht.
- DistributedData-Keys sammeln sich —
LWWMapmit Millionen Keys. - 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.# Heap-Dump über Runtime-Tools:node --inspect / Buns ProfilerPrüfe Mailbox-Sizing + die Leak-Muster in Event-Stream.
Symptom: HTTP-Latenz unter Last hoch
Abschnitt betitelt „Symptom: HTTP-Latenz unter Last hoch“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.
Tests + Dev
Abschnitt betitelt „Tests + Dev“Symptom: Tests hängen am Ende
Abschnitt betitelt „Symptom: Tests hängen am Ende“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.
Symptom: meine Nachricht ist verschwunden
Abschnitt betitelt „Symptom: meine Nachricht ist verschwunden“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/apiSuche 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öheactor-ts.diagnostics.log-dead-lettersoder setzeactor-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
DeadLetterauf dem Event-Stream oder schalte die Queue mitactor-ts.dead-letters.store = "memory"ein und lies sie mitsystem.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.
Symptom: Shutdown hat meine Nachrichten verworfen
Abschnitt betitelt „Symptom: Shutdown hat meine Nachrichten verworfen“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 ihmactor-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 eintellaus einem Promise, das ein Handler ohneawaitgestartet hat, kommt an, nachdem der Baum ruhig aussieht. Awaite es oder schicke es stattdessen als Nachricht. - Sie war an
/systemadressiert. 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.
Symptom: Flaky timing-sensitive Tests
Abschnitt betitelt „Symptom: Flaky timing-sensitive Tests“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.
Womit anfangen, wenn nichts offensichtlich ist
Abschnitt betitelt „Womit anfangen, wenn nichts offensichtlich ist“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 zum Reden bringen
Abschnitt betitelt „Das Framework zum Reden bringen“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.
Wohin als nächstes
Abschnitt betitelt „Wohin als nächstes“- 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.
