로깅

Mayros는 두 곳에 로그를 기록합니다:

Gateway가 작성하는 파일 로그 (JSON 줄).
터미널 및 Control UI에 표시되는 콘솔 출력.

이 페이지에서는 로그의 위치, 읽는 방법, 로그 레벨 및 형식을 구성하는 방법을 설명합니다.

로그 위치

기본적으로 Gateway는 다음 위치에 롤링 로그 파일을 작성합니다:

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

날짜는 게이트웨이 호스트의 로컬 시간대를 사용합니다.

~/.mayros/mayros.json에서 이를 재정의할 수 있습니다:

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

로그 읽기 방법

CLI: 실시간 tail (권장)

CLI를 사용하여 RPC를 통해 게이트웨이 로그 파일을 tail하세요:

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 탭은 logs.tail을 사용하여 동일한 파일을 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에 의해 제어됩니다.

로깅 구성

모든 로깅 구성은 ~/.mayros/mayros.json의 logging 아래에 있습니다.

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: 사람 친화적, 색상 지정, 타임스탬프 포함.
compact: 더 긴밀한 출력 (긴 세션에 가장 적합).
json: 줄당 JSON (로그 프로세서용).

편집

도구 요약은 콘솔에 도달하기 전에 민감한 토큰을 편집할 수 있습니다:

logging.redactSensitive: off | tools (기본값: tools)
logging.redactPatterns: 기본 세트를 재정의하는 정규식 문자열 목록

편집은 콘솔 출력에만 영향을 미치며 파일 로그를 변경하지 않습니다.

진단 + OpenTelemetry

진단은 모델 실행 및 메시지 흐름 원격 측정(웹훅, 대기열, 세션 상태)에 대한 구조화되고 기계 판독 가능한 이벤트입니다. 로그를 대체하지 않습니다. 메트릭, 추적 및 기타 내보내기 프로그램을 공급하기 위해 존재합니다.

진단 이벤트는 프로세스 내에서 내보내지지만 내보내기 프로그램은 진단 + 내보내기 프로그램 플러그인이 활성화된 경우에만 연결됩니다.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): 추적, 메트릭 및 로그를 위한 데이터 모델 + SDK.
OTLP: OTel 데이터를 수집기/백엔드로 내보내는 데 사용되는 유선 프로토콜.
Mayros는 현재 **OTLP/HTTP (protobuf)**를 통해 내보냅니다.

내보낸 신호

메트릭: 카운터 + 히스토그램 (토큰 사용량, 메시지 흐름, 대기열).
추적: 모델 사용량 + 웹훅/메시지 처리를 위한 스팬.
로그: diagnostics.otel.logs가 활성화된 경우 OTLP를 통해 내보내집니다. 로그 볼륨이 높을 수 있습니다. logging.level 및 내보내기 프로그램 필터를 염두에 두세요.

진단 이벤트 카탈로그

모델 사용량:

model.usage: 토큰, 비용, 기간, 컨텍스트, 공급자/모델/채널, 세션 ID.

메시지 흐름:

webhook.received: 채널당 웹훅 수신.
webhook.processed: 웹훅 처리 + 기간.
webhook.error: 웹훅 핸들러 오류.
message.queued: 처리를 위해 대기 중인 메시지.
message.processed: 결과 + 기간 + 선택적 오류.

대기열 + 세션:

queue.lane.enqueue: 명령 대기열 레인 enqueue + 깊이.
queue.lane.dequeue: 명령 대기열 레인 dequeue + 대기 시간.
session.state: 세션 상태 전환 + 이유.
session.stuck: 세션 스턱 경고 + 나이.
run.attempt: 실행 재시도/시도 메타데이터.
diagnostic.heartbeat: 집계 카운터 (웹훅/대기열/세션).

진단 활성화 (내보내기 프로그램 없음)

플러그인 또는 사용자 정의 싱크에서 진단 이벤트를 사용할 수 있도록 하려면 다음을 사용하세요:

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

진단 플래그 (대상 로그)

logging.level을 올리지 않고 추가 대상 디버그 로그를 켜려면 플래그를 사용하세요. 플래그는 대소문자를 구분하지 않으며 와일드카드를 지원합니다(예: telegram.* 또는 *).

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

환경 재정의 (일회성):

MAYROS_DIAGNOSTICS=telegram.http,telegram.payload

참고 사항:

플래그 로그는 표준 로그 파일(logging.file과 동일)로 이동합니다.
출력은 여전히 logging.redactSensitive에 따라 편집됩니다.
전체 가이드: /diagnostics/flags.

OpenTelemetry로 내보내기

진단은 diagnostics-otel 플러그인(OTLP/HTTP)을 통해 내보낼 수 있습니다. 이는 OTLP/HTTP를 허용하는 모든 OpenTelemetry 수집기/백엔드에서 작동합니다.

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