usage-logging
用于审计跟踪、成本跟踪和分析的会话感知使用日志基础设施。提供JSONL格式的结构化日志和会话管理。触发器:使用日志、审计跟踪、成本跟踪、会话日志、分析、结构化日志、JSONL、使用指标。适用场景:实施审计跟踪、跟踪成本、收集使用分析数据、管理基于会话的日志。不适用场景:简单操作且无需日志记录。在实施使用日志和审计跟踪时咨询此技能。
name: usage-logging description: |
Triggers: usage, metrics, logging, analytics, sessions Session-aware usage logging for audit trails, cost tracking, and analytics with JSONL format.
Triggers: usage logging, audit trails, cost tracking, session logging, analytics, structured logging, JSONL
Use when: implementing audit trails, tracking costs, collecting usage analytics, managing session logging
DO NOT use when: simple operations without logging needs.
Consult this skill when implementing usage logging and audit trails. category: infrastructure tags: [logging, usage, audit, metrics, sessions, analytics] dependencies: [] tools: [usage-logger] 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 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
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
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