name: usage-logging description: Consult this skill when implementing usage logging and audit trails. version: 1.9.3 alwaysApply: false Use when implementing audit trails, tracking costs, collecting usage analytics, managing session logging. Do not use when simple operations without logging needs. category: infrastructure tags:
- logging
- usage
- audit
- metrics
- sessions
- analytics
dependencies: []
tools: []
provides:
infrastructure:
- usage-logging
- session-management
- audit-trails patterns:
- structured-logging
- metrics-collection
- cost-tracking usage_patterns:
- audit-logging
- cost-tracking
- usage-analytics
- session-management complexity: beginner model_hint: fast estimated_tokens: 450 progressive_loading: true modules:
- modules/session-patterns.md
- modules/log-formats.md
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:
- 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
Verification: Run the command with --help flag to verify availability.
Detailed Resources
- Session Patterns: See
modules/session-patterns.mdfor session management - Log Formats: See
modules/log-formats.mdfor structured formats
Exit Criteria
- Operation logged with all required fields
- Session tracked for grouping
- Logs queryable for analytics