/usage-logging

name: usage-logging
description: Implements structured usage logging and audit trails for cost and session tracking. Use when adding audit trails, usage analytics, or cost tracking to a skill.
alwaysApply: false
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](#overview)
• [When to Use](#when-to-use)
• [Core Concepts](#core-concepts)
• [Session Management](#session-management)
• [Log Entry Structure](#log-entry-structure)
• [Quick Start](#quick-start)
• [Initialize Logger](#initialize-logger)
• [Log Operations](#log-operations)
• [Query Usage](#query-usage)
• [Integration Pattern](#integration-pattern)
• [Log Storage](#log-storage)
• [Detailed Resources](#detailed-resources)
• [Exit Criteria](#exit-criteria)

Usage Logging

Overview

Records individual call costs and usage events. For aggregate budget enforcement, use quota-management.

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