Logging

Mayros दो स्थानों पर लॉग करता है:

File logs (JSON lines) Gateway द्वारा लिखे गए।
Console output टर्मिनलों और Control UI में दिखाया गया।

यह पृष्ठ बताता है कि लॉग कहां रहते हैं, उन्हें कैसे पढ़ें, और लॉग स्तरों और formats को कैसे कॉन्फ़िगर करें।

लॉग कहाँ रहते हैं

डिफ़ॉल्ट रूप से, Gateway के तहत एक rolling log file लिखता है:

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

तारीख gateway host के स्थानीय timezone का उपयोग करती है।

आप इसे ~/.mayros/mayros.json में ओवरराइड कर सकते हैं:

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

लॉग कैसे पढ़ें

CLI: live tail (अनुशंसित)

RPC के माध्यम से gateway log file को tail करने के लिए CLI का उपयोग करें:

bash
mayros logs --follow

Output मोड:

TTY sessions: सुंदर, रंगीन, संरचित लॉग लाइनें।
Non-TTY sessions: सादा पाठ।
--json: line-delimited JSON (प्रति line एक लॉग event)।
--plain: TTY sessions में सादा पाठ force करें।
--no-color: ANSI रंग अक्षम करें।

JSON मोड में, CLI type-tagged objects उत्सर्जित करता है:

meta: stream metadata (file, cursor, size)
log: parsed log entry
notice: truncation / rotation संकेत
raw: unparsed log line

यदि Gateway अगम्य है, तो CLI चलाने के लिए एक छोटा संकेत प्रिंट करता है:

bash
mayros doctor

Control UI (web)

Control UI का Logs टैब logs.tail का उपयोग करके उसी file को tail करता है। इसे कैसे खोलें इसके लिए /web/control-ui देखें।

केवल-channel लॉग

Channel गतिविधि (WhatsApp/Telegram/आदि) फ़िल्टर करने के लिए, उपयोग करें:

bash
mayros channels logs --channel whatsapp

लॉग formats

File logs (JSONL)

लॉग file में प्रत्येक लाइन एक JSON object है। CLI और Control UI इन entries को संरचित output (time, level, subsystem, message) render करने के लिए parse करते हैं।

Console output

Console लॉग TTY-aware हैं और पठनीयता के लिए formatted हैं:

Subsystem prefixes (जैसे gateway/channels/whatsapp)
Level coloring (info/warn/error)
वैकल्पिक compact या JSON मोड

Console formatting logging.consoleStyle द्वारा नियंत्रित है।

Logging कॉन्फ़िगर करना

सभी logging कॉन्फ़िगरेशन ~/.mayros/mayros.json में logging के तहत रहता है।

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

Log स्तर

logging.level: file logs (JSONL) स्तर।
logging.consoleLevel: console verbosity स्तर।

--verbose केवल console output को प्रभावित करता है; यह file log स्तर नहीं बदलता।

Console शैलियाँ

logging.consoleStyle:

pretty: मानव-अनुकूल, रंगीन, timestamps के साथ।
compact: सख्त output (लंबे सत्रों के लिए सर्वश्रेष्ठ)।
json: प्रति line JSON (लॉग प्रोसेसर के लिए)।

Redaction

Tool summaries console पर पहुंचने से पहले संवेदनशील टोकन को redact कर सकते हैं:

logging.redactSensitive: off | tools (डिफ़ॉल्ट: tools)
logging.redactPatterns: डिफ़ॉल्ट सेट को ओवरराइड करने के लिए regex strings की सूची

Redaction केवल console output को प्रभावित करता है और file logs को बदलता नहीं है।

Diagnostics model runs और message-flow telemetry (webhooks, queueing, session state) के लिए संरचित, machine-readable events हैं। वे लॉग को प्रतिस्थापित नहीं करते; वे metrics, traces और अन्य exporters को feed करने के लिए मौजूद हैं।

Diagnostics events in-process उत्सर्जित होते हैं, लेकिन exporters केवल तभी attach होते हैं जब diagnostics + exporter plugin सक्षम हों।

OpenTelemetry बनाम OTLP

OpenTelemetry (OTel): traces, metrics और logs के लिए डेटा मॉडल + SDKs।
OTLP: collector/backend में OTel डेटा export करने के लिए उपयोग किया जाने वाला wire protocol।
Mayros आज OTLP/HTTP (protobuf) के माध्यम से export करता है।

Signals exported

Metrics: counters + histograms (token usage, message flow, queueing)।
Traces: model usage + webhook/message processing के लिए spans।
Logs: OTLP पर exported जब diagnostics.otel.logs सक्षम हो। लॉग वॉल्यूम उच्च हो सकता है; logging.level और exporter filters को ध्यान में रखें।

Diagnostic event catalog

Model usage:

model.usage: tokens, cost, duration, context, provider/model/channel, session ids।

Message flow:

webhook.received: प्रति channel webhook ingress।
webhook.processed: webhook handled + duration।
webhook.error: webhook handler त्रुटियां।
message.queued: processing के लिए संदेश enqueued।
message.processed: outcome + duration + वैकल्पिक त्रुटि।

Queue + session:

queue.lane.enqueue: command queue lane enqueue + depth।
queue.lane.dequeue: command queue lane dequeue + wait time।
session.state: session state transition + कारण।
session.stuck: session stuck चेतावनी + आयु।
run.attempt: run retry/attempt metadata।
diagnostic.heartbeat: aggregate counters (webhooks/queue/session)।

Diagnostics सक्षम करें (कोई exporter नहीं)

यदि आप diagnostics events को plugins या custom sinks के लिए उपलब्ध कराना चाहते हैं तो इसका उपयोग करें:

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

Diagnostics flags (लक्षित लॉग)

logging.level बढ़ाए बिना अतिरिक्त, लक्षित debug लॉग चालू करने के लिए flags का उपयोग करें। Flags case-insensitive हैं और wildcards का समर्थन करते हैं (जैसे telegram.* या *)।

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

Env override (एक बार):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

नोट्स:

Flag लॉग standard log file (same as logging.file) में जाते हैं।
Output अभी भी logging.redactSensitive के अनुसार redact है।
पूर्ण guide: /diagnostics/flags।

OpenTelemetry में export करें

Diagnostics को diagnostics-otel plugin (OTLP/HTTP) के माध्यम से exported किया जा सकता है। यह किसी भी 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
    }
  }
}