Logging

Mayros mencatat log di dua tempat:

File log (baris JSON) ditulis oleh Gateway.
Output konsol ditampilkan di terminal dan Control UI.

Halaman ini menjelaskan di mana log berada, cara membacanya, dan cara mengonfigurasi level dan format log.

Di mana log berada

Secara default, Gateway menulis file log rolling di bawah:

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

Tanggal menggunakan timezone lokal host gateway.

Anda dapat menggantinya di ~/.mayros/mayros.json:

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

Cara membaca log

CLI: live tail (direkomendasikan)

Gunakan CLI untuk tail file log gateway melalui RPC:

bash
mayros logs --follow

Mode output:

Sesi TTY: pretty, berwarna, baris log terstruktur.
Sesi non-TTY: teks biasa.
--json: JSON yang dibatasi baris (satu event log per baris).
--plain: paksa teks biasa di sesi TTY.
--no-color: nonaktifkan warna ANSI.

Dalam mode JSON, CLI mengeluarkan objek yang ditandai type:

meta: metadata stream (file, cursor, size)
log: entri log yang diparsing
notice: petunjuk truncation / rotation
raw: baris log yang tidak diparsing

Jika Gateway tidak dapat dijangkau, CLI mencetak petunjuk singkat untuk menjalankan:

bash
mayros doctor

Control UI (web)

Tab Logs Control UI tail file yang sama menggunakan logs.tail. Lihat /web/control-ui untuk cara membukanya.

Log khusus channel

Untuk memfilter aktivitas channel (WhatsApp/Telegram/dll), gunakan:

bash
mayros channels logs --channel whatsapp

Format log

File log (JSONL)

Setiap baris dalam file log adalah objek JSON. CLI dan Control UI mem-parsing entri ini untuk merender output terstruktur (waktu, level, subsistem, pesan).

Output konsol

Log konsol TTY-aware dan diformat untuk keterbacaan:

Prefix subsistem (misalnya gateway/channels/whatsapp)
Pewarnaan level (info/warn/error)
Mode compact atau JSON opsional

Formatting konsol dikontrol oleh logging.consoleStyle.

Mengonfigurasi logging

Semua konfigurasi logging berada di bawah logging di ~/.mayros/mayros.json.

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

Level log

logging.level: level file log (JSONL).
logging.consoleLevel: level verbositas konsol.

--verbose hanya mempengaruhi output konsol; itu tidak mengubah level file log.

Gaya konsol

logging.consoleStyle:

pretty: ramah manusia, berwarna, dengan timestamp.
compact: output lebih ketat (terbaik untuk sesi panjang).
json: JSON per baris (untuk prosesor log).

Redaksi

Ringkasan tool dapat menyunting token sensitif sebelum masuk ke konsol:

logging.redactSensitive: off | tools (default: tools)
logging.redactPatterns: daftar string regex untuk mengganti set default

Redaksi mempengaruhi output konsol saja dan tidak mengubah file log.

Diagnostik adalah event terstruktur yang dapat dibaca mesin untuk run model dan telemetri aliran pesan (webhook, queueing, state sesi). Mereka tidak menggantikan log; mereka ada untuk memberi makan metrik, traces, dan eksporter lainnya.

Event diagnostik dipancarkan in-process, tetapi eksporter hanya melampirkan ketika diagnostik + plugin eksporter diaktifkan.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): model data + SDK untuk traces, metrik, dan log.
OTLP: protokol wire yang digunakan untuk mengekspor data OTel ke collector/backend.
Mayros mengekspor melalui OTLP/HTTP (protobuf) hari ini.

Sinyal yang diekspor

Metrik: counter + histogram (penggunaan token, aliran pesan, queueing).
Traces: span untuk penggunaan model + pemrosesan webhook/pesan.
Log: diekspor melalui OTLP ketika diagnostics.otel.logs diaktifkan. Volume log bisa tinggi; perhatikan logging.level dan filter eksporter.

Katalog event diagnostik

Penggunaan model:

model.usage: token, biaya, durasi, konteks, provider/model/channel, id sesi.

Aliran pesan:

webhook.received: ingress webhook per channel.
webhook.processed: webhook ditangani + durasi.
webhook.error: error handler webhook.
message.queued: pesan diantrekan untuk pemrosesan.
message.processed: hasil + durasi + error opsional.

Queue + sesi:

queue.lane.enqueue: enqueue lane antrian command + kedalaman.
queue.lane.dequeue: dequeue lane antrian command + waktu tunggu.
session.state: transisi state sesi + alasan.
session.stuck: peringatan sesi stuck + usia.
run.attempt: metadata retry/percobaan run.
diagnostic.heartbeat: counter agregat (webhook/queue/sesi).

Aktifkan diagnostik (tanpa eksporter)

Gunakan ini jika Anda ingin event diagnostik tersedia untuk plugin atau sink kustom:

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

Flag diagnostik (log yang ditargetkan)

Gunakan flag untuk mengaktifkan log debug ekstra yang ditargetkan tanpa menaikkan logging.level. Flag tidak peka huruf besar-kecil dan mendukung wildcard (misalnya telegram.* atau *).

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

Override env (satu kali):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Catatan:

Log flag masuk ke file log standar (sama dengan logging.file).
Output masih disunting sesuai logging.redactSensitive.
Panduan lengkap: /diagnostics/flags.

Ekspor ke OpenTelemetry

Diagnostik dapat diekspor melalui plugin diagnostics-otel (OTLP/HTTP). Ini berfungsi dengan collector/backend OpenTelemetry apa pun yang menerima 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
    }
  }
}