ログ機能と設定

Komugi は、日々の運用ログから切断・移動パケットの精密な追跡まで、柔軟かつ高速なロギング機構を備えています。

ログ出力先の設定 (`LOG_OUTPUT`)

環境変数 LOG_OUTPUT により、ログの保存先を切り替えます:

モード名	設定値	説明
標準出力	`stdout` (既定)	コンソール (標準出力) へリアルタイムに出力します。Docker / systemd コンテナ環境に最適です。
ファイル	`file`	`LOG_FILE` で指定されたパスへ書き込みます。UTC 日付が変わると自動的に `komugi-YYYY-MM-DD.log` にローテーションされます。
SQLite DB	`sqlite`	`LOG_DB_PATH` (既定: `./komugi-logs.db`) に保存。WAL モードとマイクロバッチ書き込みにより低負荷で高速に検索可能です。
無効	`none`	運用ログやパケットログを書き込みません (致命的エラーは標準エラーへ出力されます)。

パケットロギング (`LOG_PACKETS` / `LOG_PACKET_ALLOWLIST`)

中継される Minecraft パケットの本文をログに記録するかどうかを制御します。

1. 既定の推奨構成 (許可リスト方式)

Minecraft の通信量は毎秒数千〜数万パケットに達するため、全パケットを記録するとストレージが急速に圧迫されます。そのため、Komugi は既定で移動・切断調査の核心パケットのみを記録する許可リスト方式を採用しています。

# 全パケット記録は通常 false 推奨
LOG_PACKETS=false

# 特定のパケットのみ記録 (未指定時の既定セット: 接続・切断・移動・実績等)
# command_request, command_output, transfer, disconnect,
# change_dimension, start_game, play_status, toast_request, award_achievement

2. チャットや追加パケットを追跡したい場合

既定の許可リストに加えてチャット (text) なども記録したい場合は、カンマ区切りで上書き指定します:

LOG_PACKET_ALLOWLIST=command_request,command_output,transfer,disconnect,change_dimension,start_game,play_status,toast_request,award_achievement,text

SQLite ログのテーブル定義

LOG_OUTPUT=sqlite を使用した場合、以下のスキーマでテーブルが自動作成されます:

CREATE TABLE logs (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  timestamp INTEGER NOT NULL, -- Unix エポックミリ秒 (インデックスあり)
  created_at TEXT NOT NULL,    -- ISO 8601 文字列 (例: "2026-10-01T08:00:00.000Z")
  level TEXT NOT NULL,         -- 'info' | 'warn' | 'error' (インデックスあり)
  message TEXT NOT NULL        -- ログ本文
);

クエリ実行例 (sqlite3 CLI)

# 直近 20 件のエラーログを取得
sqlite3 ./komugi-logs.db "SELECT created_at, message FROM logs WHERE level = 'error' ORDER BY id DESC LIMIT 20;"

# 特定プレイヤーの切断ログを抽出
sqlite3 ./komugi-logs.db "SELECT created_at, message FROM logs WHERE message LIKE '%Steve%' AND message LIKE '%切断%' ORDER BY id DESC;"

高速分析 (DuckDB を使う場合)

SQLite ファイルを DuckDB に直接アタッチして時間帯別の集計を行うことも可能です:

ATTACH './komugi-logs.db' AS logs (TYPE SQLITE);

SELECT
  strftime('%Y-%m-%d %H:00', to_timestamp(timestamp / 1000)) AS hour,
  level,
  count(*) AS count
FROM logs.logs
GROUP BY hour, level
ORDER BY hour DESC;