Logging

Mayros ghi log ở hai nơi:

File log (JSON line) được viết bởi Gateway.
Console output hiển thị trong terminal và Control UI.

Trang này giải thích nơi log nằm, cách đọc chúng và cách cấu hình mức log và định dạng.

Nơi log nằm

Mặc định, Gateway viết file log luân phiên dưới:

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

Ngày sử dụng múi giờ local của host gateway.

Bạn có thể ghi đè điều này trong ~/.mayros/mayros.json:

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

Cách đọc log

CLI: live tail (khuyến nghị)

Sử dụng CLI để tail file log gateway qua RPC:

bash
mayros logs --follow

Chế độ output:

Phiên TTY: dòng log đẹp, màu sắc, có cấu trúc.
Phiên không TTY: text đơn giản.
--json: JSON phân tách dòng (một sự kiện log mỗi dòng).
--plain: buộc text đơn giản trong phiên TTY.
--no-color: tắt màu ANSI.

Trong chế độ JSON, CLI phát ra các đối tượng được gắn thẻ type:

meta: metadata stream (file, cursor, size)
log: mục log đã phân tích
notice: gợi ý cắt ngắn / luân phiên
raw: dòng log chưa phân tích

Nếu Gateway không thể truy cập, CLI in gợi ý ngắn để chạy:

bash
mayros doctor

Control UI (web)

Tab Logs của Control UI tail cùng file sử dụng logs.tail. Xem /web/control-ui để biết cách mở nó.

Log chỉ kênh

Để lọc hoạt động kênh (WhatsApp/Telegram/v.v.), sử dụng:

bash
mayros channels logs --channel whatsapp

Định dạng log

File log (JSONL)

Mỗi dòng trong file log là một đối tượng JSON. CLI và Control UI phân tích các mục này để hiển thị output có cấu trúc (thời gian, mức, hệ thống con, tin nhắn).

Console output

Log console nhận biết TTY và được định dạng để dễ đọc:

Tiền tố hệ thống con (ví dụ: gateway/channels/whatsapp)
Tô màu mức (info/warn/error)
Chế độ compact hoặc JSON tùy chọn

Định dạng console được kiểm soát bởi logging.consoleStyle.

Cấu hình logging

Tất cả cấu hình logging nằm dưới logging trong ~/.mayros/mayros.json.

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

Mức log

logging.level: mức file log (JSONL).
logging.consoleLevel: mức chi tiết console.

--verbose chỉ ảnh hưởng console output; nó không thay đổi mức file log.

Kiểu console

logging.consoleStyle:

pretty: thân thiện với con người, màu sắc, với timestamp.
compact: output gọn hơn (tốt nhất cho phiên dài).
json: JSON mỗi dòng (cho bộ xử lý log).

Redaction

Tóm tắt công cụ có thể redact token nhạy cảm trước khi chúng đến console:

logging.redactSensitive: off | tools (mặc định: tools)
logging.redactPatterns: danh sách chuỗi regex để ghi đè tập mặc định

Redaction chỉ ảnh hưởng console output và không thay đổi file log.

Diagnostics là các sự kiện có cấu trúc, có thể đọc được bằng máy cho model run và telemetry message-flow (webhook, xếp hàng, trạng thái phiên). Chúng không thay thế log; chúng tồn tại để cung cấp metric, trace và các exporter khác.

Các sự kiện diagnostics được phát ra trong process, nhưng exporter chỉ đính kèm khi diagnostics + plugin exporter được bật.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): mô hình dữ liệu + SDK cho trace, metric và log.
OTLP: giao thức dây để export dữ liệu OTel đến collector/backend.
Mayros export qua OTLP/HTTP (protobuf) ngày nay.

Signal được export

Metric: counter + histogram (sử dụng token, message flow, xếp hàng).
Trace: span cho sử dụng model + xử lý webhook/message.
Log: export qua OTLP khi diagnostics.otel.logs được bật. Khối lượng log có thể cao; lưu ý logging.level và bộ lọc exporter.

Catalog sự kiện diagnostic

Sử dụng model:

model.usage: token, chi phí, thời lượng, ngữ cảnh, provider/model/channel, id phiên.

Message flow:

webhook.received: webhook ingress mỗi kênh.
webhook.processed: webhook được xử lý + thời lượng.
webhook.error: lỗi handler webhook.
message.queued: tin nhắn được xếp hàng để xử lý.
message.processed: kết quả + thời lượng + lỗi tùy chọn.

Queue + session:

queue.lane.enqueue: xếp hàng lane lệnh + độ sâu.
queue.lane.dequeue: dequeue lane lệnh + thời gian chờ.
session.state: chuyển trạng thái phiên + lý do.
session.stuck: cảnh báo phiên bị kẹt + tuổi.
run.attempt: metadata thử lại/attempt run.
diagnostic.heartbeat: counter tổng hợp (webhook/queue/session).

Bật diagnostics (không có exporter)

Sử dụng điều này nếu bạn muốn sự kiện diagnostics có sẵn cho plugin hoặc sink tùy chỉnh:

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

Flag diagnostics (log được nhắm mục tiêu)

Sử dụng flag để bật log debug bổ sung, được nhắm mục tiêu mà không tăng logging.level. Flag không phân biệt chữ hoa chữ thường và hỗ trợ ký tự đại diện (ví dụ: telegram.* hoặc *).

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

Ghi đè env (một lần):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Lưu ý:

Log flag đi đến file log tiêu chuẩn (giống logging.file).
Output vẫn được redact theo logging.redactSensitive.
Hướng dẫn đầy đủ: /diagnostics/flags.

Export sang OpenTelemetry

Diagnostics có thể được export qua plugin diagnostics-otel (OTLP/HTTP). Điều này hoạt động với bất kỳ collector/backend OpenTelemetry nào chấp nhận 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
    }
  }
}