Logowanie

Mayros loguje w dwóch miejscach:

Logi plików (linie JSON) zapisywane przez Gateway.
Wyjście konsoli wyświetlane w terminalach i interfejsie sterowania.

Ta strona wyjaśnia, gdzie znajdują się logi, jak je czytać i jak konfigurować poziomy logów i formaty.

Gdzie znajdują się logi

Domyślnie Gateway zapisuje obracający się plik logów pod:

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

Data używa lokalnej strefy czasowej hosta gateway.

Możesz to zmienić w ~/.mayros/mayros.json:

json
{
  "logging": {
    "file": "/path/to/mayros.log"
  }
}

Jak czytać logi

CLI: śledzenie na żywo (zalecane)

Użyj CLI do śledzenia pliku logów gateway przez RPC:

bash
mayros logs --follow

Tryby wyjścia:

Sesje TTY: ładne, kolorowe, strukturalne linie logów.
Sesje non-TTY: zwykły tekst.
--json: linie rozdzielone JSON (jedno zdarzenie logowania na linię).
--plain: wymuś zwykły tekst w sesjach TTY.
--no-color: wyłącz kolory ANSI.

W trybie JSON, CLI emituje obiekty oznaczone type:

meta: metadane strumienia (plik, kursor, rozmiar)
log: sparsowany wpis logu
notice: wskazówki obcięcia / rotacji
raw: nie sparsowana linia logu

Jeśli Gateway jest niedostępny, CLI wyświetla krótką wskazówkę do uruchomienia:

bash
mayros doctor

Interfejs sterowania (web)

Zakładka Logs interfejsu sterowania śledzi ten sam plik używając logs.tail. Zobacz /web/control-ui jak go otworzyć.

Logi tylko kanałów

Aby filtrować aktywność kanałów (WhatsApp/Telegram/itp.), użyj:

bash
mayros channels logs --channel whatsapp

Formaty logów

Logi plików (JSONL)

Każda linia w pliku logów to obiekt JSON. CLI i interfejs sterowania parsują te wpisy, aby renderować strukturalne wyjście (czas, poziom, podsystem, wiadomość).

Wyjście konsoli

Logi konsoli są świadome TTY i sformatowane dla czytelności:

Prefiksy podsystemów (np. gateway/channels/whatsapp)
Kolorowanie poziomów (info/warn/error)
Opcjonalny tryb kompaktowy lub JSON

Formatowanie konsoli jest kontrolowane przez logging.consoleStyle.

Konfiguracja logowania

Cała konfiguracja logowania znajduje się pod logging w ~/.mayros/mayros.json.

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

Poziomy logów

logging.level: poziom logów plików (JSONL).
logging.consoleLevel: poziom szczegółowości konsoli.

--verbose wpływa tylko na wyjście konsoli; nie zmienia poziomów logów plików.

Style konsoli

logging.consoleStyle:

pretty: przyjazny dla człowieka, kolorowy, ze znacznikami czasu.
compact: bardziej zwarty wynik (najlepszy dla długich sesji).
json: JSON na linię (dla procesorów logów).

Redakcja

Podsumowania narzędzi mogą redagować wrażliwe tokeny zanim trafią do konsoli:

logging.redactSensitive: off | tools (domyślnie: tools)
logging.redactPatterns: lista ciągów regex do nadpisania domyślnego zestawu

Redakcja wpływa tylko na wyjście konsoli i nie zmienia logów plików.

Diagnostyka to strukturalne, czytelne dla maszyny zdarzenia dla uruchomień modelu i telemetrii przepływu wiadomości (webhooki, kolejkowanie, stan sesji). Nie zastępują logów; istnieją, aby zasilać metryki, ślady i inne eksportery.

Zdarzenia diagnostyczne są emitowane w procesie, ale eksportery dołączają się tylko, gdy diagnostyka + wtyczka eksportera są włączone.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): model danych + SDK dla śladów, metryk i logów.
OTLP: protokół przewodowy używany do eksportu danych OTel do kolektora/backendu.
Mayros eksportuje przez OTLP/HTTP (protobuf) obecnie.

Eksportowane sygnały

Metryki: liczniki + histogramy (użycie tokenów, przepływ wiadomości, kolejkowanie).
Ślady: spany dla użycia modelu + przetwarzania webhook/wiadomości.
Logi: eksportowane przez OTLP gdy diagnostics.otel.logs jest włączony. Objętość logów może być wysoka; pamiętaj o logging.level i filtrach eksportera.

Katalog zdarzeń diagnostycznych

Użycie modelu:

model.usage: tokeny, koszt, czas trwania, kontekst, dostawca/model/kanał, identyfikatory sesji.

Przepływ wiadomości:

webhook.received: wejście webhooka na kanał.
webhook.processed: webhook obsłużony + czas trwania.
webhook.error: błędy obsługi webhooka.
message.queued: wiadomość w kolejce do przetworzenia.
message.processed: wynik + czas trwania + opcjonalny błąd.

Kolejka + sesja:

queue.lane.enqueue: kolejkowanie ścieżki kolejki poleceń + głębokość.
queue.lane.dequeue: usuwanie z kolejki ścieżki kolejki poleceń + czas oczekiwania.
session.state: przejście stanu sesji + powód.
session.stuck: ostrzeżenie o zawieszeniu sesji + wiek.
run.attempt: metadane ponowienia/próby uruchomienia.
diagnostic.heartbeat: zagregowane liczniki (webhooki/kolejka/sesja).

Włączanie diagnostyki (bez eksportera)

Użyj tego, jeśli chcesz, aby zdarzenia diagnostyczne były dostępne dla wtyczek lub niestandardowych ujść:

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

Flagi diagnostyczne (ukierunkowane logi)

Użyj flag, aby włączyć dodatkowe, ukierunkowane logi debugowania bez podnoszenia logging.level. Flagi nie rozróżniają wielkości liter i obsługują symbole wieloznaczne (np. telegram.* lub *).

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

Nadpisanie env (jednorazowe):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Uwagi:

Logi flag trafiają do standardowego pliku logów (ten sam co logging.file).
Wyjście jest nadal redagowane zgodnie z logging.redactSensitive.
Pełny przewodnik: /diagnostics/flags.

Eksport do OpenTelemetry

Diagnostyka może być eksportowana przez wtyczkę diagnostics-otel (OTLP/HTTP). Działa to z dowolnym kolektorem/backendem OpenTelemetry, który akceptuje OTLP/HTTP.

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
    }
  }
}