การบันทึก

Mayros บันทึกในสองที่:

  • บันทึกไฟล์ (บรรทัด JSON) เขียนโดย Gateway
  • เอาต์พุตคอนโซล แสดงในเทอร์มินัลและ Control UI

หน้านี้อธิบายว่าบันทึกอยู่ที่ไหน วิธีการอ่าน และวิธีการกำหนดค่า ระดับและรูปแบบของบันทึก

บันทึกอยู่ที่ไหน

ตามค่าเริ่มต้น Gateway เขียนไฟล์บันทึกแบบหมุนเวียนภายใต้:

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

วันที่ใช้เขตเวลาโลคัลของโฮสต์ Gateway

คุณสามารถแทนที่สิ่งนี้ใน ~/.mayros/mayros.json:

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

วิธีการอ่านบันทึก

CLI: ติดตามสด (แนะนำ)

ใช้ CLI เพื่อติดตามไฟล์บันทึก Gateway ผ่าน RPC:

bash
mayros logs --follow

โหมดเอาต์พุต:

  • เซสชัน TTY: บรรทัดบันทึกที่มีโครงสร้าง สวยงาม มีสี
  • เซสชันที่ไม่ใช่ TTY: ข้อความธรรมดา
  • --json: JSON แยกด้วยบรรทัด (เหตุการณ์บันทึกหนึ่งต่อบรรทัด)
  • --plain: บังคับข้อความธรรมดาในเซสชัน TTY
  • --no-color: ปิดใช้งานสี ANSI

ในโหมด JSON CLI จะส่งออกออบเจ็กต์ที่แท็กด้วย type:

  • meta: เมทาดาต้าสตรีม (ไฟล์, เคอร์เซอร์, ขนาด)
  • log: รายการบันทึกที่แยกวิเคราะห์แล้ว
  • notice: คำใบ้การตัดทอน / หมุนเวียน
  • raw: บรรทัดบันทึกที่ยังไม่แยกวิเคราะห์

หาก Gateway ไม่สามารถเข้าถึงได้ CLI จะพิมพ์คำใบ้สั้นๆ ให้เรียกใช้:

bash
mayros doctor

Control UI (เว็บ)

แท็บ บันทึก ของ Control UI ติดตามไฟล์เดียวกันโดยใช้ logs.tail ดู /web/control-ui สำหรับวิธีการเปิด

บันทึกเฉพาะช่องทาง

เพื่อกรองกิจกรรมช่องทาง (WhatsApp/Telegram/ฯลฯ) ให้ใช้:

bash
mayros channels logs --channel whatsapp

รูปแบบบันทึก

บันทึกไฟล์ (JSONL)

แต่ละบรรทัดในไฟล์บันทึกเป็นออบเจ็กต์ JSON CLI และ Control UI แยกวิเคราะห์ รายการเพื่อแสดงผลเอาต์พุตที่มีโครงสร้าง (เวลา, ระดับ, ระบบย่อย, ข้อความ)

เอาต์พุตคอนโซล

บันทึกคอนโซลเป็น ตระหนักถึง TTY และจัดรูปแบบเพื่อความสามารถในการอ่าน:

  • คำนำหน้าระบบย่อย (เช่น gateway/channels/whatsapp)
  • การระบายสีระดับ (info/warn/error)
  • โหมดแบบกะทัดรัดหรือ JSON ตัวเลือก

การจัดรูปแบบคอนโซลถูกควบคุมโดย logging.consoleStyle

กำหนดค่าการบันทึก

การกำหนดค่าการบันทึกทั้งหมดอยู่ภายใต้ logging ใน ~/.mayros/mayros.json

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

ระดับบันทึก

  • logging.level: ระดับ บันทึกไฟล์ (JSONL)
  • logging.consoleLevel: ระดับความละเอียดของ คอนโซล

--verbose ส่งผลต่อเอาต์พุตคอนโซลเท่านั้น ไม่เปลี่ยนระดับบันทึกไฟล์

สไตล์คอนโซล

logging.consoleStyle:

  • pretty: เป็นมิตรกับมนุษย์ มีสี พร้อม timestamp
  • compact: เอาต์พุตที่กระชับกว่า (ดีที่สุดสำหรับเซสชันยาว)
  • json: JSON ต่อบรรทัด (สำหรับตัวประมวลผลบันทึก)

การปกปิด

สรุปเครื่องมือสามารถปกปิดโทเค็นที่ละเอียดอ่อนก่อนที่จะเข้าสู่คอนโซล:

  • logging.redactSensitive: off | tools (ค่าเริ่มต้น: tools)
  • logging.redactPatterns: รายการสตริง regex เพื่อแทนที่ชุดเริ่มต้น

การปกปิดส่งผลต่อ เอาต์พุตคอนโซลเท่านั้น และไม่เปลี่ยนแปลงบันทึกไฟล์

การวินิจฉัย + OpenTelemetry

การวินิจฉัยเป็นเหตุการณ์ที่มีโครงสร้างและอ่านได้ด้วยเครื่องสำหรับการรันโมเดล และ เทเลเมทรีการไหลของข้อความ (webhooks, การจัดคิว, สถานะเซสชัน) พวกเขา ไม่ แทนที่บันทึก พวกเขามีอยู่เพื่อป้อนเมตริก, traces และ exporters อื่นๆ

เหตุการณ์การวินิจฉัยถูกปล่อยในโปรเซส แต่ exporters ติดเมื่อ การวินิจฉัย + ปลั๊กอิน exporter เปิดใช้งานเท่านั้น

OpenTelemetry vs OTLP

  • OpenTelemetry (OTel): โมเดลข้อมูล + SDK สำหรับ traces, metrics และ logs
  • OTLP: โปรโตคอลสายที่ใช้เพื่อส่งออกข้อมูล OTel ไปยัง collector/backend
  • Mayros ส่งออกผ่าน OTLP/HTTP (protobuf) วันนี้

สัญญาณที่ส่งออก

  • Metrics: ตัวนับ + ฮิสโตแกรม (การใช้โทเค็น, การไหลของข้อความ, การจัดคิว)
  • Traces: span สำหรับการใช้โมเดล + การประมวลผล webhook/message
  • Logs: ส่งออกผ่าน OTLP เมื่อเปิดใช้งาน diagnostics.otel.logs ปริมาณบันทึก สามารถสูงได้ จำ logging.level และตัวกรอง exporter ไว้ในใจ

แค็ตตาล็อกเหตุการณ์การวินิจฉัย

การใช้โมเดล:

  • model.usage: โทเค็น, ต้นทุน, ระยะเวลา, บริบท, provider/model/channel, ID เซสชัน

การไหลของข้อความ:

  • webhook.received: webhook ingress ต่อช่องทาง
  • webhook.processed: webhook จัดการ + ระยะเวลา
  • webhook.error: ข้อผิดพลาดของตัวจัดการ webhook
  • message.queued: ข้อความเข้าคิวเพื่อการประมวลผล
  • message.processed: ผลลัพธ์ + ระยะเวลา + ข้อผิดพลาดตัวเลือก

คิว + เซสชัน:

  • queue.lane.enqueue: การเข้าคิวเลนคิวคำสั่ง + ความลึก
  • queue.lane.dequeue: การออกจากคิวเลนคิวคำสั่ง + เวลารอ
  • session.state: การเปลี่ยนสถานะเซสชัน + เหตุผล
  • session.stuck: คำเตือนเซสชันติด + อายุ
  • run.attempt: เมทาดาต้าการลองใหม่/ความพยายามในการรัน
  • diagnostic.heartbeat: ตัวนับรวม (webhooks/queue/session)

เปิดใช้งานการวินิจฉัย (ไม่มี exporter)

ใช้สิ่งนี้หากคุณต้องการเหตุการณ์การวินิจฉัยพร้อมใช้งานสำหรับปลั๊กอินหรือ sink แบบกำหนดเอง:

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

แฟล็กการวินิจฉัย (บันทึกแบบกำหนดเป้าหมาย)

ใช้แฟล็กเพื่อเปิดบันทึกดีบักพิเศษแบบกำหนดเป้าหมายโดยไม่ยก logging.level แฟล็กไม่คำนึงถึงตัวพิมพ์ใหญ่-เล็กและรองรับไวด์การ์ด (เช่น telegram.* หรือ *)

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

การแทนที่ Env (ครั้งเดียว):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

หมายเหตุ:

  • บันทึกแฟล็กไปที่ไฟล์บันทึกมาตรฐาน (เหมือนกับ logging.file)
  • เอาต์พุตยังคงถูกปกปิดตาม logging.redactSensitive
  • คู่มือเต็ม: /diagnostics/flags

ส่งออกไปยัง OpenTelemetry

การวินิจฉัยสามารถส่งออกผ่านปลั๊กอิน diagnostics-otel (OTLP/HTTP) นี่ ทำงานกับ OpenTelemetry collector/backend ใดๆ ที่ยอมรับ 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
    }
  }
}

หมายเหตุ:

  • คุณยังสามารถเปิดใช้งานปลั๊กอินด้วย mayros plugins enable diagnostics-otel
  • protocol รองรับ http/protobuf เท่านั้นในปัจจุบัน grpc ถูกละเว้น
  • Metrics รวมการใช้โทเค็น, ต้นทุน, ขนาดบริบท, ระยะเวลาการรัน และการนับ/ฮิสโตแกรมการไหลของข้อความ (webhooks, การจัดคิว, สถานะเซสชัน, ความลึก/การรอของคิว)
  • Traces/metrics สามารถสลับด้วย traces / metrics (ค่าเริ่มต้น: เปิด) Traces รวม span การใช้โมเดลและ span การประมวลผล webhook/message เมื่อเปิดใช้งาน
  • ตั้งค่า headers เมื่อ collector ของคุณต้องการการพิสูจน์ตัวตน
  • ตัวแปรสภาพแวดล้อมที่รองรับ: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL

เมตริกที่ส่งออก (ชื่อ + ประเภท)

การใช้โมเดล:

  • mayros.tokens (counter, attrs: mayros.token, mayros.channel, mayros.provider, mayros.model)
  • mayros.cost.usd (counter, attrs: mayros.channel, mayros.provider, mayros.model)
  • mayros.run.duration_ms (histogram, attrs: mayros.channel, mayros.provider, mayros.model)
  • mayros.context.tokens (histogram, attrs: mayros.context, mayros.channel, mayros.provider, mayros.model)

การไหลของข้อความ:

  • mayros.webhook.received (counter, attrs: mayros.channel, mayros.webhook)
  • mayros.webhook.error (counter, attrs: mayros.channel, mayros.webhook)
  • mayros.webhook.duration_ms (histogram, attrs: mayros.channel, mayros.webhook)
  • mayros.message.queued (counter, attrs: mayros.channel, mayros.source)
  • mayros.message.processed (counter, attrs: mayros.channel, mayros.outcome)
  • mayros.message.duration_ms (histogram, attrs: mayros.channel, mayros.outcome)

คิว + เซสชัน:

  • mayros.queue.lane.enqueue (counter, attrs: mayros.lane)
  • mayros.queue.lane.dequeue (counter, attrs: mayros.lane)
  • mayros.queue.depth (histogram, attrs: mayros.lane หรือ mayros.channel=heartbeat)
  • mayros.queue.wait_ms (histogram, attrs: mayros.lane)
  • mayros.session.state (counter, attrs: mayros.state, mayros.reason)
  • mayros.session.stuck (counter, attrs: mayros.state)
  • mayros.session.stuck_age_ms (histogram, attrs: mayros.state)
  • mayros.run.attempt (counter, attrs: mayros.attempt)

Span ที่ส่งออก (ชื่อ + คุณลักษณะหลัก)

  • mayros.model.usage
    • mayros.channel, mayros.provider, mayros.model
    • mayros.sessionKey, mayros.sessionId
    • mayros.tokens.* (input/output/cache_read/cache_write/total)
  • mayros.webhook.processed
    • mayros.channel, mayros.webhook, mayros.chatId
  • mayros.webhook.error
    • mayros.channel, mayros.webhook, mayros.chatId, mayros.error
  • mayros.message.processed
    • mayros.channel, mayros.outcome, mayros.chatId, mayros.messageId, mayros.sessionKey, mayros.sessionId, mayros.reason
  • mayros.session.stuck
    • mayros.state, mayros.ageMs, mayros.queueDepth, mayros.sessionKey, mayros.sessionId

การสุ่มตัวอย่าง + การล้าง

  • การสุ่มตัวอย่าง trace: diagnostics.otel.sampleRate (0.0–1.0, root spans เท่านั้น)
  • ช่วงเวลาการส่งออกเมตริก: diagnostics.otel.flushIntervalMs (ขั้นต่ำ 1000ms)

หมายเหตุโปรโตคอล

  • OTLP/HTTP endpoints สามารถตั้งค่าผ่าน diagnostics.otel.endpoint หรือ OTEL_EXPORTER_OTLP_ENDPOINT
  • หาก endpoint มี /v1/traces หรือ /v1/metrics แล้ว จะใช้ตามที่เป็น
  • หาก endpoint มี /v1/logs แล้ว จะใช้ตามที่เป็นสำหรับบันทึก
  • diagnostics.otel.logs เปิดใช้งานการส่งออกบันทึก OTLP สำหรับเอาต์พุต logger หลัก

พฤติกรรมการส่งออกบันทึก

  • บันทึก OTLP ใช้ระเบียนที่มีโครงสร้างเดียวกันที่เขียนไปที่ logging.file
  • เคารพ logging.level (ระดับบันทึกไฟล์) การปกปิดคอนโซล ไม่ ใช้ กับบันทึก OTLP
  • การติดตั้งปริมาณสูงควรชอบการสุ่มตัวอย่าง/การกรอง OTLP collector

เคล็ดลับการแก้ไขปัญหา

  • Gateway ไม่สามารถเข้าถึงได้? เรียกใช้ mayros doctor ก่อน
  • บันทึกว่างเปล่า? ตรวจสอบว่า Gateway กำลังทำงานและเขียนไปที่เส้นทางไฟล์ ใน logging.file
  • ต้องการรายละเอียดเพิ่มเติม? ตั้งค่า logging.level เป็น debug หรือ trace และลองใหม่