Usage Logging

Table of Contents

• Overview
• When to Use
• Core Concepts
• Session Management
• Log Entry Structure
• Quick Start
• Initialize Logger
• Log Operations
• Query Usage
• Integration Pattern
• Log Storage
• Detailed Resources
• Exit Criteria

Usage Logging

Overview

Session-aware logging infrastructure for tracking operations across plugins. Provides structured JSONL logging with automatic session management for audit trails and analytics.

When To Use

• Need audit trails for operations
• Tracking costs across sessions
• Building usage analytics
• Debugging with operation history

When NOT To Use

• Simple operations without logging needs

Core Concepts

Session Management

Sessions group related operations:

• Auto-created on first operation
• Timeout after 1 hour of inactivity
• Unique session IDs for tracking

Log Entry Structure

{
  "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": {}
}

Verification: Run the command with --help flag to verify availability.

Quick Start

Initialize Logger

from leyline.usage_logger import UsageLogger

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

Verification: Run the command with --help flag to verify availability.

Log Operations

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

Verification: Run the command with --help flag to verify availability.

Query Usage

# 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)

Verification: Run the command with --help flag to verify availability.

Integration Pattern

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

Verification: Run the command with --help flag to verify availability.

Standard integration flow:

1. Initialize logger for your service
2. Log operations after completion
3. Query for analytics and debugging

Log Storage

Default location: ~/.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

Verification: Run the command with --help flag to verify availability.

Detailed Resources

• Session Patterns: See modules/session-patterns.md for session management
• Log Formats: See modules/log-formats.md for structured formats

Exit Criteria

• Operation logged with all required fields
• Session tracked for grouping
• Logs queryable for analytics

Troubleshooting

Common Issues

Command not found Ensure all dependencies are installed and in PATH

Permission errors Check file permissions and run with appropriate privileges

Unexpected behavior Enable verbose logging with --verbose flag