mcpField
U
usage-logging

usage-logging

github.com/atholaDevelopment34399 installsUpdated 1d ago
Repository

About usage-logging

usage-logging is a session-aware skill for recording operation usage and costs in structured JSONL logs. It is intended for teams that need audit trails, cross-session cost tracking, analytics, or debugging history.

Key features

  1. 01Automatic session creation and timeout
  2. 02Structured JSONL operation logs
  3. 03Recent-operation queries
  4. 04Usage and estimated-cost summaries

Use cases

  1. 01Auditing service operations
  2. 02Tracking token use and costs across sessions
  3. 03Analyzing recent usage
  4. 04Debugging from operation history

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/athola/claude-night-market --skill usage-logging

After installing, type/usage-loggingin Claude Code to confirm it loaded.

Bundled filesmodules/log-formats.mdmodules/session-patterns.md

Details

From the project README

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

Comments

Markdown supported