Logging

Mayros loggt an zwei Stellen:

Datei-Logs (JSON-Zeilen), die vom Gateway geschrieben werden.
Konsolenausgabe, die in Terminals und der Control UI angezeigt wird.

Diese Seite erklärt, wo sich Logs befinden, wie man sie liest und wie man Log-Level und Formate konfiguriert.

Wo sich Logs befinden

Standardmäßig schreibt das Gateway eine rollierende Log-Datei unter:

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

Das Datum verwendet die lokale Zeitzone des Gateway-Hosts.

Sie können dies in ~/.mayros/mayros.json überschreiben:

json
{
  "logging": {
    "file": "/pfad/zu/mayros.log"
  }
}

Wie man Logs liest

CLI: Live-Tail (empfohlen)

Verwenden Sie die CLI, um die Gateway-Log-Datei via RPC zu verfolgen:

bash
mayros logs --follow

Ausgabemodi:

TTY-Sessions: hübsch, farbig, strukturierte Log-Zeilen.
Nicht-TTY-Sessions: einfacher Text.
--json: Zeilen-delimitiertes JSON (ein Log-Event pro Zeile).
--plain: erzwingt einfachen Text in TTY-Sessions.
--no-color: deaktiviert ANSI-Farben.

Im JSON-Modus gibt die CLI type-markierte Objekte aus:

meta: Stream-Metadaten (Datei, Cursor, Größe)
log: geparster Log-Eintrag
notice: Kürzungs-/Rotationshinweise
raw: ungeparste Log-Zeile

Wenn das Gateway nicht erreichbar ist, zeigt die CLI einen kurzen Hinweis zur Ausführung:

bash
mayros doctor

Control UI (Web)

Der Logs-Tab der Control UI verfolgt dieselbe Datei mit logs.tail. Siehe /web/control-ui zum Öffnen.

Nur-Channel-Logs

Um Channel-Aktivität zu filtern (WhatsApp/Telegram/etc), verwenden Sie:

bash
mayros channels logs --channel whatsapp

Log-Formate

Datei-Logs (JSONL)

Jede Zeile in der Log-Datei ist ein JSON-Objekt. Die CLI und Control UI parsen diese Einträge, um strukturierte Ausgabe zu rendern (Zeit, Level, Subsystem, Nachricht).

Konsolenausgabe

Konsolen-Logs sind TTY-aware und für Lesbarkeit formatiert:

Subsystem-Präfixe (z.B. gateway/channels/whatsapp)
Level-Färbung (info/warn/error)
Optionaler kompakter oder JSON-Modus

Die Konsolenformatierung wird durch logging.consoleStyle gesteuert.

Logging konfigurieren

Alle Logging-Konfigurationen befinden sich unter logging in ~/.mayros/mayros.json.

json
{
  "logging": {
    "level": "info",
    "file": "/tmp/mayros/mayros-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

Log-Level

logging.level: Datei-Logs (JSONL) Level.
logging.consoleLevel: Konsolen-Verbositätslevel.

--verbose beeinflusst nur die Konsolenausgabe; es ändert nicht die Datei-Log-Level.

Konsolen-Stile

logging.consoleStyle:

pretty: benutzerfreundlich, farbig, mit Zeitstempeln.
compact: kompaktere Ausgabe (am besten für lange Sessions).
json: JSON pro Zeile (für Log-Prozessoren).

Schwärzung

Tool-Zusammenfassungen können sensible Tokens schwärzen, bevor sie die Konsole erreichen:

logging.redactSensitive: off | tools (Standard: tools)
logging.redactPatterns: Liste von Regex-Strings zum Überschreiben des Standardsatzes

Schwärzung betrifft nur Konsolenausgabe und ändert keine Datei-Logs.

Diagnostics sind strukturierte, maschinenlesbare Events für Modell-Runs und Nachrichten-Fluss-Telemetrie (Webhooks, Queuing, Session-State). Sie ersetzen nicht Logs; sie existieren, um Metriken, Traces und andere Exporters zu füttern.

Diagnostics-Events werden In-Process ausgegeben, aber Exporters hängen sich nur an, wenn Diagnostics + der Exporter-Plugin aktiviert sind.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): das Datenmodell + SDKs für Traces, Metriken und Logs.
OTLP: das Wire-Protokoll zum Exportieren von OTel-Daten zu einem Collector/Backend.
Mayros exportiert via OTLP/HTTP (protobuf) heute.

Exportierte Signale

Metriken: Zähler + Histogramme (Token-Nutzung, Nachrichten-Fluss, Queuing).
Traces: Spans für Modell-Nutzung + Webhook/Nachrichten-Verarbeitung.
Logs: über OTLP exportiert, wenn diagnostics.otel.logs aktiviert ist. Log-Volumen kann hoch sein; behalten Sie logging.level und Exporter-Filter im Auge.

Diagnostic-Event-Katalog

Modell-Nutzung:

model.usage: Tokens, Kosten, Dauer, Kontext, Provider/Model/Channel, Session-IDs.

Nachrichten-Fluss:

webhook.received: Webhook-Ingress pro Channel.
webhook.processed: Webhook behandelt + Dauer.
webhook.error: Webhook-Handler-Fehler.
message.queued: Nachricht zur Verarbeitung in Warteschlange.
message.processed: Ergebnis + Dauer + optionaler Fehler.

Queue + Session:

queue.lane.enqueue: Command-Queue-Lane enqueue + Tiefe.
queue.lane.dequeue: Command-Queue-Lane dequeue + Wartezeit.
session.state: Session-State-Übergang + Grund.
session.stuck: Session-Stuck-Warnung + Alter.
run.attempt: Run-Retry/Versuchs-Metadaten.
diagnostic.heartbeat: Aggregierte Zähler (Webhooks/Queue/Session).

Diagnostics aktivieren (kein Exporter)

Verwenden Sie dies, wenn Sie möchten, dass Diagnostics-Events für Plugins oder benutzerdefinierte Sinks verfügbar sind:

json
{
  "diagnostics": {
    "enabled": true
  }
}

Diagnostics-Flags (gezielte Logs)

Verwenden Sie Flags, um zusätzliche, gezielte Debug-Logs zu aktivieren, ohne logging.level zu erhöhen. Flags sind case-insensitive und unterstützen Wildcards (z.B. telegram.* oder *).

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

Env-Override (einmalig):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Hinweise:

Flag-Logs gehen in die Standard-Log-Datei (gleich wie logging.file).
Ausgabe ist weiterhin geschwärzt gemäß logging.redactSensitive.
Vollständiger Leitfaden: /diagnostics/flags.

Nach OpenTelemetry exportieren

Diagnostics können via diagnostics-otel-Plugin (OTLP/HTTP) exportiert werden. Dies funktioniert mit jedem OpenTelemetry-Collector/Backend, das OTLP/HTTP akzeptiert.

json
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "mayros-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}