Logimine

Mayros logib kahte kohta:

Faililogi (JSON read), mille kirjutab Gateway.
Konsooliväljund, mis kuvatakse terminalides ja Control UI-s.

See lehekülg selgitab, kus logid asuvad, kuidas neid lugeda ja kuidas konfigureerida logi tasemeid ja formaate.

Kus logid asuvad

Vaikimisi kirjutab Gateway pöörleva logifaili asukohta:

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

Kuupäev kasutab gateway hosti kohalikku ajavööndit.

Sa saad seda ~/.mayros/mayros.json failis alistada:

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

Kuidas logisid lugeda

CLI: reaalajas jälgimine (soovitatav)

Kasuta CLI-d, et jälgida gateway logifaili RPC kaudu:

bash
mayros logs --follow

Väljundi režiimid:

TTY sessioonid: ilus, värviline, struktureeritud logiread.
Mitte-TTY sessioonid: lihttekst.
--json: rea eraldatud JSON (üks logiüritus rea kohta).
--plain: sunni lihttekst TTY sessioonides.
--no-color: keela ANSI värvid.

JSON režiimis emiteerib CLI type-ga märgistatud objekte:

meta: voo metaandmed (fail, kursor, suurus)
log: parseeritud logikirje
notice: lühendamise / pööramise vihjed
raw: parseerimata logirida

Kui Gateway ei ole kättesaadav, prindib CLI lühikese vihje käivitamiseks:

bash
mayros doctor

Control UI (veeb)

Control UI Logs vahekaart jälgib sama faili kasutades logs.tail. Vaata /web/control-ui, kuidas seda avada.

Ainult kanali logid

Kanali tegevuse filtreerimiseks (WhatsApp/Telegram/jne), kasuta:

bash
mayros channels logs --channel whatsapp

Logi formaadid

Faililogi (JSONL)

Iga rida logifailis on JSON objekt. CLI ja Control UI parsivad neid kirjeid struktureeritud väljundi renderdamiseks (aeg, tase, alamsüsteem, sõnum).

Konsooliväljund

Konsoolilogi on TTY-teadlik ja vormindatud loetavuseks:

Alamsüsteemi eesliited (nt gateway/channels/whatsapp)
Taseme värvimine (info/warn/error)
Valikuline kompaktne või JSON režiim

Konsooli vormindust kontrollib logging.consoleStyle.

Logimise konfigureerimine

Kogu logimise konfiguratsioon asub logging all ~/.mayros/mayros.json failis.

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

Logi tasemed

logging.level: faililogi (JSONL) tase.
logging.consoleLevel: konsooli üksikasjalikkuse tase.

--verbose mõjutab ainult konsooli väljundit; see ei muuda faili logi tasemeid.

Konsooli stiilid

logging.consoleStyle:

pretty: inimlikult sõbralik, värviline, ajatemplitega.
compact: tihedam väljund (parim pikaajalistele sessioonidele).
json: JSON rea kohta (logiprotsessorite jaoks).

Redakteerimine

Tööriistade kokkuvõtted võivad redakteerida tundlikke tokeneid enne nende jõudmist konsooli:

logging.redactSensitive: off | tools (vaikimisi: tools)
logging.redactPatterns: regex stringide loend vaikimisi komplekti alistamiseks

Redakteerimine mõjutab ainult konsooli väljundit ega muuda faililogisid.

Diagnostika on struktureeritud, masinloetavad sündmused mudeli käitamiste ja sõnumivoo telemeetria jaoks (webhookid, järjekord, sessiooni olek). Need ei asenda logi; need eksisteerivad mõõdikute, jälgimiste ja muude eksportijate toitmiseks.

Diagnostika sündmused emitatakse protsessis, kuid eksportijad lisatakse ainult siis, kui diagnostika + eksportija plugin on lubatud.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): andmemudel + SDK-d jälgimiste, mõõdikute ja logide jaoks.
OTLP: juhtmeprotokoll, mida kasutatakse OTel andmete eksportimiseks kollektorisse/tausta.
Mayros ekspordib täna OTLP/HTTP (protobuf) kaudu.

Eksporditud signaalid

Mõõdikud: loendajad + histogrammid (tokeni kasutus, sõnumivoog, järjekord).
Jälgimised: spännid mudeli kasutuse + webhook/sõnumi töötlemise jaoks.
Logid: eksporditud OTLP kaudu, kui diagnostics.otel.logs on lubatud. Logi maht võib olla suur; pea meeles logging.level ja eksportija filtreid.

Diagnostika sündmuste kataloog

Mudeli kasutus:

model.usage: tokenid, hind, kestus, kontekst, pakkuja/mudel/kanal, sessiooni id-d.

Sõnumivoog:

webhook.received: webhook sissepääs kanali kohta.
webhook.processed: webhook käsitletud + kestus.
webhook.error: webhook käsitseja vead.
message.queued: sõnum järjekorda töötlemiseks.
message.processed: tulemus + kestus + valikuline viga.

Järjekord + sessioon:

queue.lane.enqueue: käsurea järjekorra rada järjekorda + sügavus.
queue.lane.dequeue: käsurea järjekorra rada järjekorrast + ooteaeg.
session.state: sessiooni oleku üleminek + põhjus.
session.stuck: sessiooni kinni hoiatus + vanus.
run.attempt: käitamise kordamise/katse metaandmed.
diagnostic.heartbeat: koondatud loendajad (webhookid/järjekord/sessioon).

Luba diagnostika (ilma eksportijata)

Kasuta seda, kui soovid diagnostika sündmusi pluginatele või kohandatud vajutitele:

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

Diagnostika lipud (sihitud logid)

Kasuta lippe, et sisse lülitada lisad, sihitud silumislogi ilma logging.level tõstmata. Lipud on tõstutundmatud ja toetavad metamärke (nt telegram.* või *).

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

Keskkonna alistamine (ühekordne):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Märkused:

Lipu logid lähevad standardsesse logifaili (sama mis logging.file).
Väljund on endiselt redakteeritud vastavalt logging.redactSensitive.
Täielik juhend: /diagnostics/flags.

Eksport OpenTelemetry-sse

Diagnostikat saab eksportida diagnostics-otel plugina kaudu (OTLP/HTTP). See töötab iga OpenTelemetry kollektori/taustaga, mis aktsepteerib 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
    }
  }
}