usage-logging

使用状況のログ記録

概要

個々の呼び出しコストと使用状況イベントを記録します。予算の一括適用には、quota-managementを使用してください。

プラグインをまたいで操作を追跡する、セッション対応のログ記録インフラストラクチャです。監査証跡や分析に利用できるよう、セッションを自動管理しながら構造化JSONLログを記録します。

使用する場面

• 操作の監査証跡が必要な場合
• セッションをまたいでコストを追跡する場合
• 使用状況の分析を構築する場合
• 操作履歴を使ってデバッグする場合

使用しない場面

• ログ記録が不要な単純な操作

主な概念

セッション管理

セッションは関連する操作をまとめます。

• 最初の操作時に自動作成
• 1時間操作がないとタイムアウト
• 追跡用の一意なセッション ID

ログエントリの構造

{
  "timestamp": "2025-12-05T10:30:00Z",
  "session_id": "session_1733394600",
  "service": "my-service",
  "operation": "analyze_files",
  "tokens": 5000,
  "success": true,
  "duration_seconds": 2.5,
  "metadata": {}
}

確認方法： --help フラグを付けてコマンドを実行し、利用できることを確認してください。

クイックスタート

ロガーを初期化する

from leyline.usage_logger import UsageLogger

logger = UsageLogger(service="my-service")

確認方法： --help フラグを付けてコマンドを実行し、利用できることを確認してください。

操作を記録する

logger.log_usage(
    operation="analyze_files",
    tokens=5000,
    success=True,
    duration=2.5,
    metadata={"files": 10},
)

確認方法： --help フラグを付けてコマンドを実行し、利用できることを確認してください。

使用状況を照会する

# Recent operations
recent = logger.get_recent_operations(hours=24)

# Usage summary
summary = logger.get_usage_summary(days=7)
print(f"Total tokens: {summary['total_tokens']}")
print(f"Total cost: ${summary['estimated_cost']:.2f}")

# Recent errors
errors = logger.get_recent_errors(count=10)

確認方法： --help フラグを付けてコマンドを実行し、利用できることを確認してください。

統合パターン

# In your skill's frontmatter
dependencies: [leyline:usage-logging]

確認方法： --help フラグを付けてコマンドを実行し、利用できることを確認してください。

標準的な統合フロー：

1. サービス用のロガーを初期化する
2. 操作の完了後に記録する
3. 分析やデバッグのために照会する

ログの保存先

デフォルトの保存先：~/.claude/leyline/usage/{service}.jsonl

# View recent logs
tail -20 ~/.claude/leyline/usage/my-service.jsonl | jq .

# Query by date
grep "2025-12-05" ~/.claude/leyline/usage/my-service.jsonl

確認方法： --help フラグを付けてコマンドを実行し、利用できることを確認してください。

詳細リソース

• セッションパターン：セッション管理については modules/session-patterns.md を参照してください
• ログ形式：構造化形式については modules/log-formats.md を参照してください

完了条件

• 必須フィールドをすべて含む操作ログが記録されている
• グループ化のためにセッションが追跡されている
• 分析のためにログを照会できる