デバッグモード¶

このガイドでは、kazunoko のデバッグモードを使用して、詳細な情報を収集し問題を診断する方法を説明します。

デバッグモードとは¶

デバッグモードでは、kazunoko が通常は表示しない詳細な情報（DEBUG レベルログ）を出力します。

# 通常モード（INFO レベル以上）
uv run kazunoko read 100

# デバッグモード（DEBUG レベル以上、詳細情報を表示）
uv run kazunoko --level debug read 100

デバッグモードの有効化¶

グローバルオプション `--level debug`¶

# すべてのコマンドにデバッグレベルを適用
uv run kazunoko --level debug read 100
uv run kazunoko --level debug status
uv run kazunoko --level debug measure "1:300;2:320;3:310" 100

ログレベルの選択肢¶

レベル	表示内容	用途
debug	すべての詳細情報	問題の深掘り調査
info	進捗情報	標準的な実行（デフォルト）
error	エラーのみ	本番運用

デバッグモードで得られる情報¶

ポート検出の詳細¶

uv run kazunoko --level debug status 2>&1 | grep -i "port\|detect"

出力例:

Auto-detecting port for connection
Available ports:
  - /dev/cu.usbserial-110 (OSECHI Detector)
  - /dev/cu.Bluetooth-Incoming-Port (Not a serial device)
Selected port: /dev/cu.usbserial-110

コマンド送受信の詳細¶

uv run kazunoko --level debug query "VERSION" 2>&1 | head -30

出力例:

Sending command: "VERSION"
Waiting for response with timeout: 0.1s
Response received: {"type": "response", "status": "ok", ...}

イベント読み込みの詳細¶

uv run kazunoko --level debug read 5 2>&1 | head -50

出力例:

Event 1/5: Reading from buffer (poll_count=50000)
  Attempt 1: Scanning memory buffer...
  Attempt 2: Scanning memory buffer...
  Event found after 2 attempts
  Event: {"event_count": 1, "ch": 1, ...}

Event 2/5: Reading from buffer (poll_count=50000)
  ...

デバッグ出力の保存¶

ファイルにリダイレクト¶

エラー出力（stderr）をファイルに保存します。

# デバッグ出力をファイルに保存
uv run kazunoko --level debug read 100 2> debug.log

# 標準出力（イベント）とエラー出力を分離
uv run kazunoko --level debug read 100 > events.jsonl 2> debug.log

出力内容の確認¶

# ログファイルを確認
cat debug.log | head -50

# 特定のキーワードで検索
grep -i "error\|timeout\|failed" debug.log

# パイプで処理
cat debug.log | tail -20

JSON ログファイルの活用¶

JSON ログの場所¶

# macOS
~/Library/Logs/kazunoko/kazunoko.json

# Linux
~/.local/share/kazunoko/logs/kazunoko.json

# Windows
%APPDATA%\kazunoko\logs\kazunoko.json

JSON ログから情報抽出¶

# DEBUG レベルのログのみ表示
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq 'select(.record.level.name == "DEBUG")'

# タイムスタンプとメッセージを表示
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq '{time: .record.time.repr, level: .record.level.name, message: .record.message}'

# エラーレベルのみ表示
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq 'select(.record.level.name == "ERROR")'

ログの統計分析¶

# ログレベル別の件数
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq -r '.record.level.name' | sort | uniq -c

# 特定のキーワード出現数
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq -r '.record.message' | grep -i "timeout" | wc -l

問題別のデバッグ方法¶

ポート接続が失敗する場合¶

# デバッグモードでポート検出を追跡
uv run kazunoko --level debug status 2> port_debug.log

# ログから利用可能なポートを確認
cat port_debug.log | grep -A 5 "Available ports"

# ポートを手動で指定して試す
uv run kazunoko --level debug status --port /dev/ttyUSB0 2> debug.log

コマンド送受信がタイムアウトする場合¶

# デバッグモードでコマンド送受信を追跡
uv run kazunoko --level debug query "STATUS" 2> command_debug.log

# ログからタイムアウト情報を確認
grep -i "timeout\|waiting" command_debug.log

# JSON ログから詳細情報を抽出
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq 'select(.record.message | contains("timeout"))'

イベント読み込みがスキップされる場合¶

# デバッグモードでイベント読み込みを追跡
uv run kazunoko --level debug read 100 2> event_debug.log

# スキップされたイベントを確認
grep -i "timeout\|skip\|error" event_debug.log | head -20

# JSON ログから統計を取得
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq 'select(.record.message | contains("Event")) | .record.message'

パフォーマンス分析¶

実行時間の詳細測定¶

# タイムスタンプ付きでデバッグ出力
time uv run kazunoko --level debug read 100 2> timing_debug.log > /dev/null

# ログから詳細なタイミング情報を抽出
cat ~/Library/Logs/kazunoko/kazunoko.json | \
  jq '{time: .record.time.repr, elapsed_ms: (.record.time.timestamp * 1000 | floor)}'

各段階の処理時間¶

# デバッグログから各操作の時間を推定
cat timing_debug.log | grep -E "^[0-9]+" | head -20

# タイムスタンプから処理時間を計算
python3 << 'EOF'
import json
from pathlib import Path

log_file = Path.home() / "Library/Logs/kazunoko/kazunoko.json"
times = []

with open(log_file) as f:
    for line in f:
        entry = json.loads(line)
        if "event" in entry.get("record", {}).get("message", "").lower():
            times.append(entry["record"]["time"]["timestamp"])

if len(times) > 1:
    total_time = times[-1] - times[0]
    events = len(times)
    rate = events / total_time if total_time > 0 else 0
    print(f"Total time: {total_time:.2f} seconds")
    print(f"Events: {events}")
    print(f"Rate: {rate:.1f} events/second")
EOF

デバッグレポートの作成¶

問題をメーカーやコミュニティに報告する際、デバッグレポートを作成してください。

必須情報の収集¶

# 1. デバイス情報
uv run kazunoko version > report_version.txt

# 2. デバイス状態
uv run kazunoko status > report_status.txt

# 3. デバッグログ（問題を再現）
uv run kazunoko --level debug read 10 2> report_debug.log

# 4. JSON ログファイルをコピー
cp ~/Library/Logs/kazunoko/kazunoko.json report_kazunoko.json

# 5. システム情報
python3 --version > report_python.txt
uname -a >> report_python.txt

レポートファイルの構成¶

issue_report/
├── report_version.txt          # kazunoko バージョン
├── report_status.txt           # デバイス状態
├── report_debug.log            # デバッグモード出力
├── report_kazunoko.json        # JSON ログファイル
├── report_python.txt           # Python とOS情報
└── ISSUE_DESCRIPTION.md        # 問題の説明

レポートテンプレート¶

# Issue: [問題のタイトル]

## 問題の説明

[何が起きたのか、何が期待されたのか]

## 再現手順

1. ...
2. ...
3. ...

## 環境情報

- OS: macOS / Linux / Windows
- Python: 3.x.x
- kazunoko: 0.x.x
- Device MAC: XX:XX:XX:XX:XX:XX

## 実行したコマンド

```bash
uv run kazunoko [command] [options]

エラーメッセージ¶

[エラーメッセージをコピー&ペースト]

デバッグログ¶

[report_debug.log の内容、または report_kazunoko.json をアップロード]

追加情報¶

[その他の情報があれば記入]

---

## デバッグモードの注意点

### パフォーマンスへの影響

デバッグモードは標準モードより遅くなります。

標準モード (INFO): 10-20 イベント/秒デバッグモード (DEBUG): 5-10 イベント/秒

本測定ではデバッグモードを使用しないでください。

### ログファイルのサイズ

デバッグレベルのログは急速に増加します。

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

# 大きくなった場合は削除
rm ~/Library/Logs/kazunoko/kazunoko.json

プライバシーと機密情報¶

デバッグログには以下の情報が含まれます。

ポート番号（システム構成情報）
タイムスタンプ（測定時刻）
エラー詳細（実装情報）

公開リポジトリに投稿する場合、機密情報をマスクしてください。

# MAC アドレスをマスク
sed 's/[0-9A-F]{2}:[0-9A-F]{2}:[0-9A-F]{2}:[0-9A-F]{2}:[0-9A-F]{2}:[0-9A-F]{2}/XX:XX:XX:XX:XX:XX/g' report_debug.log

高度なデバッグ技法¶

シリアル通信の低レベル監視¶

# Linux で シリアルポート通信を監視
strace -e read,write -s 200 uv run kazunoko read 5 2>&1 | grep -E "tty|USB"

# または、別ウィンドウで minicom を起動
minicom -D /dev/ttyUSB0

Python スクリプトでのデバッグ¶

from kazunoko import connect, Reader
from kazunoko.log import setup_logger
import logging

# デバッグレベルで設定
log_dir = setup_logger(log_level="debug")
logger = logging.getLogger(__name__)

try:
    with connect() as device:
        reader = Reader(device)
        for event in reader.stream_by_count(10):
            logger.debug(f"Event details: {event.model_dump()}")
            print(f"Event: {event.event_count}")
except Exception as e:
    logger.error(f"Error: {e}", exc_info=True)
    raise

メモリ使用量の追跡¶

# メモリ使用量をリアルタイム監視
ps -p $$ -o pid,%cpu,%mem,vsz,rss --header --no-headers | \
  awk '{print "PID:", $1, "CPU:", $2"%", "MEM:", $3"%", "VSZ:", $4, "RSS:", $5}'

トラブルシューティングチェックリスト¶

デバッグを開始する前に確認してください。

□ 最新バージョンを使用しているか？（uv run kazunoko version）
□ デバイスが接続されているか？（uv run kazunoko status）
□ デバイスの電源が入っているか？
□ ケーブルがしっかり接続されているか？
□ ドライバーがインストールされているか？
□ 別のプログラムがポートを使用していないか？
□ 定期的に電源を切って再起動したか？

次のステップ¶

エラーメッセージの読み方 - エラーメッセージの詳細な解釈
ログの基礎 - ログファイルの見方
よくあるご質問 - よくある問題と解決策

デバッグモード¶

デバッグモードとは¶

デバッグモードの有効化¶

グローバルオプション --level debug¶

ログレベルの選択肢¶

デバッグモードで得られる情報¶

ポート検出の詳細¶

コマンド送受信の詳細¶

イベント読み込みの詳細¶

デバッグ出力の保存¶

ファイルにリダイレクト¶

出力内容の確認¶

JSON ログファイルの活用¶

JSON ログの場所¶

JSON ログから情報抽出¶

ログの統計分析¶

問題別のデバッグ方法¶

ポート接続が失敗する場合¶

コマンド送受信がタイムアウトする場合¶

イベント読み込みがスキップされる場合¶

パフォーマンス分析¶

実行時間の詳細測定¶

各段階の処理時間¶

デバッグレポートの作成¶

必須情報の収集¶

レポートファイルの構成¶

レポートテンプレート¶

エラーメッセージ¶

デバッグログ¶

追加情報¶

プライバシーと機密情報¶

高度なデバッグ技法¶

シリアル通信の低レベル監視¶

Python スクリプトでのデバッグ¶

メモリ使用量の追跡¶

トラブルシューティングチェックリスト¶

次のステップ¶

グローバルオプション `--level debug`¶