Skip to content

ログの基礎

このガイドでは、kazunokoがどのようにログを記録しているのか、ログファイルをどう読むかについて説明します。

ログとは何か

ログ（Log） は、プログラムの実行時に記録される情報です。

  • いつ何が起きたのか
  • 何がエラーだったのか
  • デバイスの状態がどうだったのか

これらのすべてが自動的に記録されます。

ターミナルに表示されるエラーメッセージだけでは、何が原因だったのかを完全には判断できない場合があります。 そんなときにログファイルを確認することで、より詳しい情報を得られます。

ログファイルの保存先

kazunokoのログファイルは XDG Base Directory仕様 に準拠して保存されます。 各OSでのログファイルの保存場所は以下の通りです。

OS パス
macOS ~/Library/Logs/kazunoko/kazunoko.json
Linux ~/.local/share/kazunoko/logs/kazunoko.json
Windows %APPDATA%\kazunoko\logs\kazunoko.json

ログファイルは以下の形式・条件で自動的に作成されます。

  • 形式: JSON（コンピューターが読みやすい構造化形式）
  • レベル: 常にDEBUGレベル
  • 保存期間: 7日間（古いログは自動削除）
  • 更新方法: 毎日0時に新しいファイルに切り替え（ローテーション）
  • XDG準拠: 各OSのシステム標準ディレクトリに従う

ログレベルとは

ログには 重要度（レベル） があります。

レベル 意味 用途 表示例
DEBUG デバッグ情報 プログラムの動作詳細 タイミング、内部状態、引数値
INFO 情報 進捗状況 「コマンド実行開始」「接続完了」
SUCCESS 成功 重要な成功イベント 「測定完了」「保存完了」
WARNING 警告 注意が必要 「イベントをスキップ」「接続不安定」
ERROR エラー 重大な問題 「ポートが見つからない」「タイムアウト」

ログレベルは階層構造になっており、 指定したレベル以上の情報がログに記録されます。

Note

ログレベルを「WARNING」に設定すると、WARNINGとERRORのみが記録されます。 DEBUGやINFOは記録されません。

ログを確認する

新しいログはどんどんログファイルに追加されます。 tailコマンドを使って、最新のログを確認できます。

# ログファイルの最後の10行を表示
tail -10 ~/Library/Logs/kazunoko/kazunoko.json

# ログファイルの最後の20行を表示
tail -20 ~/Library/Logs/kazunoko/kazunoko.json

# ログファイルをリアルタイム表示
tail -f ~/Library/Logs/kazunoko/kazunoko.json

ログを整形する（jq）

kazunokoのログファイルはJSON形式です。 そのままでは人間には読みにくいのでjqコマンドなどで整形・抽出するのがオススメです。

tail ~/Library/Logs/kazunoko/kazunoko.json | jq .

メッセージだけを抽出

tail ~/Library/Logs/kazunoko/kazunoko.json | jq .record.message

タイムスタンプとメッセージを抽出

tail ~/Library/Logs/kazunoko/kazunoko.json | jq '{time: .record.time.repr, message: .record.message}'

エラーレベルのメッセージだけを抽出

tail ~/Library/Logs/kazunoko/kazunoko.json | jq 'select(.record.level.name == "ERROR") | .record.message'

ログから問題を診断する

例1：接続できない場合

$ tail -20 ~/Library/Logs/kazunoko/kazunoko.json | jq .record.message
"Auto-detecting port for connection"
"Auto-detecting serial port"
"No suitable port found"
"Event collection failed: No suitable serial port found for OSECHI detector.\n\nAvailable ports:\n  - /dev/cu.debug-console (n/a)\n  - /dev/cu.Bluetooth-Incoming-Port (n/a)"

診断：シリアルポートが見つからない → デバイスが接続されていない、またはドライバーがない

例2：タイムアウトが多い場合

$ cat ~/Library/Logs/kazunoko/kazunoko.json | jq 'select(.record.message | contains("EventTimeout"))'

診断：タイムアウトが多い → スレッショルド値が高すぎる、またはpoll_countが不足している

ログファイルの管理

ログディレクトリの確認

# ログディレクトリの内容を確認（macOS）
ls -la ~/Library/Logs/kazunoko/

# ログファイルのサイズを確認
du -h ~/Library/Logs/kazunoko/kazunoko.json

ログファイルの削除

ログファイルは自動的に7日後に削除されます。 手動で削除する場合はrmコマンドを使ってください。

# 古いログをすべて削除
rm -rf ~/Library/Logs/kazunoko/

# または、macOS のみ
rm ~/Library/Logs/kazunoko/kazunoko.json

--

問題報告時のログ提出

GitLabでissueを報告する際は、以下の手順でログを提供してください。

  1. 問題を再現
# デバッグレベルで実行
uv run kazunoko --level debug read 100 2> error_report.log
  1. ログファイルを確認
# macOS
cat ~/Library/Logs/kazunoko/kazunoko.json > issue_logs.json

# Linux
cat ~/.local/share/kazunoko/logs/kazunoko.json > issue_logs.json

  1. issue に添付

  2. ログファイル（issue_logs.json）

  3. エラーメッセージのスクリーンショット
  4. 実行したコマンド
  5. 環境情報（OS、Pythonバージョン、kazunokoバージョン）

詳しくはデバッグモードを参照してください。

次のステップ