Loglama

Mayros iki yerde log tutar:

Ağ Geçidi tarafından yazılan Dosya logları (JSON satırları).
Terminallerde ve Kontrol Arayüzünde gösterilen Konsol çıktısı.

Bu sayfa logların nerede olduğunu, nasıl okunacağını ve log seviyelerinin ve formatlarının nasıl yapılandırılacağını açıklar.

Loglar nerede

Varsayılan olarak, Ağ Geçidi şu konumda dönen bir log dosyası yazar:

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

Tarih, ağ geçidi ana bilgisayarının yerel saat dilimini kullanır.

Bunu ~/.mayros/mayros.json içinde geçersiz kılabilirsiniz:

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

Loglar nasıl okunur

CLI: canlı tail (önerilir)

RPC aracılığıyla ağ geçidi log dosyasını tail etmek için CLI'yi kullanın:

bash
mayros logs --follow

Çıktı modları:

TTY oturumları: güzel, renklendirilmiş, yapılandırılmış log satırları.
TTY olmayan oturumlar: düz metin.
--json: satır sınırlı JSON (satır başına bir log olayı).
--plain: TTY oturumlarında düz metni zorla.
--no-color: ANSI renklerini devre dışı bırak.

JSON modunda, CLI type etiketli nesneler yayar:

meta: akış meta verileri (dosya, imleç, boyut)
log: ayrıştırılmış log girişi
notice: kesme / döndürme ipuçları
raw: ayrıştırılmamış log satırı

Ağ Geçidine erişilemiyorsa, CLI şunu çalıştırmak için kısa bir ipucu yazdırır:

bash
mayros doctor

Kontrol Arayüzü (web)

Kontrol Arayüzünün Logs sekmesi, logs.tail kullanarak aynı dosyayı tail eder. Nasıl açılacağı için bkz. /web/control-ui.

Yalnızca kanal logları

Kanal etkinliğini filtrelemek için (WhatsApp/Telegram/vb.), şunu kullanın:

bash
mayros channels logs --channel whatsapp

Log formatları

Dosya logları (JSONL)

Log dosyasındaki her satır bir JSON nesnesidir. CLI ve Kontrol Arayüzü, yapılandırılmış çıktıyı (zaman, seviye, alt sistem, mesaj) oluşturmak için bu girişleri ayrıştırır.

Konsol çıktısı

Konsol logları TTY farkındadır ve okunabilirlik için biçimlendirilir:

Alt sistem ön ekleri (örn. gateway/channels/whatsapp)
Seviye renklendirme (info/warn/error)
İsteğe bağlı kompakt veya JSON modu

Konsol biçimlendirmesi logging.consoleStyle tarafından kontrol edilir.

Loglamayı yapılandırma

Tüm loglama yapılandırması ~/.mayros/mayros.json içinde logging altında bulunur.

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

Log seviyeleri

logging.level: dosya logları (JSONL) seviyesi.
logging.consoleLevel: konsol ayrıntı seviyesi.

--verbose yalnızca konsol çıktısını etkiler; dosya log seviyelerini değiştirmez.

Konsol stilleri

logging.consoleStyle:

pretty: insan dostu, renkli, zaman damgalı.
compact: daha sıkı çıktı (uzun oturumlar için en iyisi).
json: satır başına JSON (log işlemciler için).

Redaksiyon

Araç özetleri, konsola ulaşmadan önce hassas belirteçleri redakte edebilir:

logging.redactSensitive: off | tools (varsayılan: tools)
logging.redactPatterns: varsayılan seti geçersiz kılmak için regex dizelerinin listesi

Redaksiyon yalnızca konsol çıktısını etkiler ve dosya loglarını değiştirmez.

Tanılama, model çalıştırmaları ve mesaj akışı telemetrisi (webhooklar, kuyruklama, oturum durumu) için yapılandırılmış, makine tarafından okunabilir olaylardır. Logların yerini almazlar; metrikleri, izlemeleri ve diğer ihracatçıları beslemek için mevcutturlar.

Tanılama olayları süreç içinde yayılır, ancak ihracatçılar yalnızca tanılama + ihracatçı eklentisi etkinleştirildiğinde eklenir.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): izlemeler, metrikler ve loglar için veri modeli + SDK'lar.
OTLP: OTel verilerini bir toplayıcı/arka uca aktarmak için kullanılan tel protokolü.
Mayros bugün OTLP/HTTP (protobuf) aracılığıyla ihraç eder.

İhraç edilen sinyaller

Metrikler: sayaçlar + histogramlar (belirteç kullanımı, mesaj akışı, kuyruklama).
İzlemeler: model kullanımı + webhook/mesaj işleme için spanlar.
Loglar: diagnostics.otel.logs etkinleştirildiğinde OTLP üzerinden ihraç edilir. Log hacmi yüksek olabilir; logging.level ve ihracatçı filtrelerini aklınızda bulundurun.

Tanılama olay kataloğu

Model kullanımı:

model.usage: belirteçler, maliyet, süre, bağlam, sağlayıcı/model/kanal, oturum kimlikleri.

Mesaj akışı:

webhook.received: kanal başına webhook girişi.
webhook.processed: webhook işlendi + süre.
webhook.error: webhook işleyici hataları.
message.queued: işleme için kuyruğa alınan mesaj.
message.processed: sonuç + süre + isteğe bağlı hata.

Kuyruk + oturum:

queue.lane.enqueue: komut kuyruğu şerit kuyruğa alma + derinlik.
queue.lane.dequeue: komut kuyruğu şerit kuyruktan çıkarma + bekleme süresi.
session.state: oturum durumu geçişi + neden.
session.stuck: oturum takılma uyarısı + yaş.
run.attempt: çalıştırma yeniden deneme/deneme meta verileri.
diagnostic.heartbeat: toplam sayaçlar (webhooks/queue/session).

Tanılamayı etkinleştir (ihracatçı yok)

Tanılama olaylarının eklentiler veya özel havuzlar için kullanılabilir olmasını istiyorsanız bunu kullanın:

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

Tanılama bayrakları (hedefli loglar)

logging.level'i yükseltmeden ekstra, hedefli hata ayıklama loglarını açmak için bayrakları kullanın. Bayraklar büyük/küçük harf duyarlı değildir ve joker karakterleri destekler (örn. telegram.* veya *).

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

Env geçersiz kılma (tek seferlik):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

Notlar:

Bayrak logları standart log dosyasına gider (logging.file ile aynı).
Çıktı hala logging.redactSensitive'e göre redakte edilir.
Tam kılavuz: /diagnostics/flags.

OpenTelemetry'ye ihraç et

Tanılama, diagnostics-otel eklentisi (OTLP/HTTP) aracılığıyla ihraç edilebilir. Bu, OTLP/HTTP'yi kabul eden herhangi bir OpenTelemetry toplayıcısı/arka ucuyla çalışır.

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
    }
  }
}