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

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

Quick Start

Initialize Logger

from leyline.usage_logger import UsageLogger

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

Log Operations

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

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)

Integration Pattern

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

Standard integration flow:

Initialize logger for your service
Log operations after completion
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

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

usage-logging