ロギング

Mayrosは2か所にログを記録します：

Gatewayによって書き込まれるファイルログ（JSON行）。
ターミナルとControl UIに表示されるコンソール出力。

このページでは、ログの場所、読み方、ログレベルとフォーマットの設定方法を説明します。

ログの場所

デフォルトでは、Gatewayは以下の場所にローリングログファイルを書き込みます：

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

日付はgatewayホストのローカルタイムゾーンを使用します。

~/.mayros/mayros.jsonで上書きできます：

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

ログの読み方

CLI: ライブテール（推奨）

CLIを使用してRPC経由でgatewayログファイルをテールします：

bash
mayros logs --follow

出力モード：

TTYセッション: きれいで、カラー化され、構造化されたログ行。
非TTYセッション: プレーンテキスト。
--json: 行区切りJSON（1行に1つのログイベント）。
--plain: TTYセッションでプレーンテキストを強制。
--no-color: ANSIカラーを無効化。

JSONモードでは、CLIはtypeタグ付きオブジェクトを出力します：

meta: ストリームメタデータ（ファイル、カーソル、サイズ）
log: 解析されたログエントリ
notice: 切り捨て/ローテーションヒント
raw: 未解析ログ行

Gatewayに到達できない場合、CLIは以下を実行するための短いヒントを表示します：

bash
mayros doctor

Control UI（Web）

Control UIのLogsタブは、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によって制御されます。

ロギングの設定

すべてのロギング設定は、~/.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: 1行にJSON（ログプロセッサ用）。

リダクション

ツールサマリーは、コンソールに到達する前に機密トークンをリダクションできます：

logging.redactSensitive: off | tools（デフォルト：tools）
logging.redactPatterns: デフォルトセットを上書きする正規表現文字列のリスト

リダクションはコンソール出力のみに影響し、ファイルログは変更しません。

診断 + OpenTelemetry

診断は、モデル実行および メッセージフローテレメトリ（Webhook、キューイング、セッション状態）のための構造化された機械可読イベントです。ログを置き換えるものではありません。メトリクス、トレース、その他のエクスポーターに供給するために存在します。

診断イベントはプロセス内で発行されますが、エクスポーターは診断 + エクスポータープラグインが有効になっている場合にのみアタッチされます。

OpenTelemetry vs OTLP

OpenTelemetry（OTel）: トレース、メトリクス、ログのデータモデル + SDK。
OTLP: OTelデータをコレクター/バックエンドにエクスポートするために使用されるワイヤプロトコル。
Mayrosは今日**OTLP/HTTP（protobuf）**経由でエクスポートします。

エクスポートされるシグナル

メトリクス: カウンター + ヒストグラム（トークン使用量、メッセージフロー、キューイング）。
トレース: モデル使用 + Webhook/メッセージ処理のスパン。
ログ: diagnostics.otel.logsが有効な場合、OTLP経由でエクスポート。ログボリュームは高くなる可能性があります。logging.levelとエクスポーターフィルターに注意してください。

診断イベントカタログ

モデル使用：

model.usage: トークン、コスト、期間、コンテキスト、プロバイダー/モデル/チャネル、セッションID。

メッセージフロー：

webhook.received: チャネルごとのWebhookイングレス。
webhook.processed: Webhook処理 + 期間。
webhook.error: Webhookハンドラーエラー。
message.queued: 処理のためにキューに入れられたメッセージ。
message.processed: 結果 + 期間 + オプションのエラー。

キュー + セッション：

queue.lane.enqueue: コマンドキューレーンエンキュー + 深さ。
queue.lane.dequeue: コマンドキューレーンデキュー + 待機時間。
session.state: セッション状態遷移 + 理由。
session.stuck: セッションスタック警告 + 経過時間。
run.attempt: 再試行/試行メタデータを実行。
diagnostic.heartbeat: 集約カウンター（Webhook/キュー/セッション）。

診断を有効化（エクスポーターなし）

プラグインまたはカスタムシンクで診断イベントを利用可能にしたい場合は、これを使用します：

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