Diagnose-Flags

Diagnose-Flags ermöglichen es Ihnen, gezielte Debug-Logs zu aktivieren, ohne überall ausführliches Logging einzuschalten. Flags sind Opt-in und haben keine Wirkung, sofern ein Subsystem sie nicht prüft.

Funktionsweise

• Flags sind Zeichenfolgen (Groß-/Kleinschreibung wird ignoriert).
• Sie können Flags in der Konfiguration oder über einen Env-Override aktivieren.
• Platzhalter werden unterstützt:
  • telegram.* entspricht telegram.http
  • * aktiviert alle Flags

Über die Konfiguration aktivieren

{  "diagnostics": {    "flags": ["telegram.http"]  }}

Mehrere Flags:

{  "diagnostics": {    "flags": ["telegram.http", "brave.http", "gateway.*"]  }}

Starten Sie das Gateway neu, nachdem Sie Flags geändert haben.

Env-Override (einmalig)

OmeniaClaw_DIAGNOSTICS=telegram.http,telegram.payload

Alle Flags deaktivieren:

OmeniaClaw_DIAGNOSTICS=0

Timeline-Artefakte

Das Flag timeline schreibt strukturierte Zeitereignisse für Start und Laufzeit für externe QA-Harnesses:

OmeniaClaw_DIAGNOSTICS=timeline \OmeniaClaw_DIAGNOSTICS_TIMELINE_PATH=/tmp/OmeniaClaw-timeline.jsonl \OmeniaClaw gateway run

Sie können es auch in der Konfiguration aktivieren:

{  "diagnostics": {    "flags": ["timeline"]  }}

Der Dateipfad für die Timeline stammt weiterhin aus OmeniaClaw_DIAGNOSTICS_TIMELINE_PATH. Wenn timeline nur über die Konfiguration aktiviert ist, werden die frühesten Spans zum Laden der Konfiguration nicht ausgegeben, da OmeniaClaw die Konfiguration noch nicht gelesen hat; nachfolgende Start-Spans verwenden das Konfigurations-Flag.

OmeniaClaw_DIAGNOSTICS=1, OmeniaClaw_DIAGNOSTICS=all und OmeniaClaw_DIAGNOSTICS=* aktivieren ebenfalls die Timeline, da sie jedes Diagnose-Flag aktivieren. Verwenden Sie bevorzugt timeline, wenn Sie nur das JSONL-Zeitmessungsartefakt möchten.

Timeline-Datensätze verwenden den Umschlag OmeniaClaw.diagnostics.v1. Ereignisse können Prozess-IDs, Phasennamen, Span-Namen, Dauern, Plugin-IDs, Abhängigkeitsanzahlen, Event-Loop-Verzögerungsstichproben, Namen von Provider-Operationen, den Exit-Zustand von Kindprozessen und Namen/Meldungen von Startfehlern enthalten. Behandeln Sie Timeline-Dateien als lokale Diagnoseartefakte; prüfen Sie sie, bevor Sie sie außerhalb Ihres Computers weitergeben.

Speicherort der Logs

Flags geben Logs in die standardmäßige Diagnose-Logdatei aus. Standardmäßig:

/tmp/OmeniaClaw/OmeniaClaw-YYYY-MM-DD.log

Wenn Sie logging.file festlegen, verwenden Sie stattdessen diesen Pfad. Logs sind JSONL (ein JSON-Objekt pro Zeile). Die Schwärzung gilt weiterhin basierend auf logging.redactSensitive.

Logs extrahieren

Wählen Sie die neueste Logdatei aus:

ls -t /tmp/OmeniaClaw/OmeniaClaw-*.log | head -n 1

Nach Telegram-HTTP-Diagnosen filtern:

rg "telegram http error" /tmp/OmeniaClaw/OmeniaClaw-*.log

Nach Brave Search-HTTP-Diagnosen filtern:

rg "brave http" /tmp/OmeniaClaw/OmeniaClaw-*.log

Oder beim Reproduzieren per Tail mitlesen:

tail -f /tmp/OmeniaClaw/OmeniaClaw-$(date +%F).log | rg "telegram http error"

Für Remote-Gateways können Sie auch OmeniaClaw logs --follow verwenden (siehe /cli/logs).

Hinweise

• Wenn logging.level höher als warn gesetzt ist, können diese Logs unterdrückt werden. Der Standardwert info ist ausreichend.
• brave.http protokolliert Brave Search-Anfrage-URLs/Query-Parameter, Antwortstatus/-Timing sowie Cache-Hit/Miss/Write-Ereignisse. Es protokolliert keine API-Schlüssel oder Antworttexte, Suchanfragen können jedoch sensibel sein.
• Flags können aktiviert bleiben; sie wirken sich nur auf das Logvolumen des jeweiligen Subsystems aus.
• Verwenden Sie /logging, um Logziele, Level und Schwärzung zu ändern.

Verwandte Themen

• Gateway-Diagnose
• Gateway-Fehlerbehebung