Back to Details

usage-logging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Table of Contents

目录

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.
支持会话感知的跨插件操作跟踪日志基础设施，提供结构化JSONL日志能力，自带自动会话管理功能，可用于审计追踪和数据分析。

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
会话会对相关操作进行分组：
  • 首次操作时自动创建
  • 无活动1小时后超时
  • 采用唯一会话ID进行跟踪

Log Entry Structure

日志条目结构

json
{
  "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.
json
{
  "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": {}
}
验证： 运行带
--help
参数的命令验证功能是否可用。

Quick Start

快速入门

Initialize Logger

初始化日志器

python
from leyline.usage_logger import UsageLogger

logger = UsageLogger(service="my-service")
Verification: Run the command with 
--help
flag to verify availability.
python
from leyline.usage_logger import UsageLogger

logger = UsageLogger(service="my-service")
验证： 运行带
--help
参数的命令验证功能是否可用。

Log Operations

日志操作

python
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.
python
logger.log_usage(
    operation="analyze_files",
    tokens=5000,
    success=True,
    duration=2.5,
    metadata={"files": 10}
)
验证： 运行带
--help
参数的命令验证功能是否可用。

Query Usage

查询使用情况

python
undefined
python
undefined

Recent operations

最近操作

recent = logger.get_recent_operations(hours=24)
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}")
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.
errors = logger.get_recent_errors(count=10)
**验证：** 运行带`--help`参数的命令验证功能是否可用。

Integration Pattern

集成模式

yaml
undefined
yaml
undefined

In your skill's frontmatter

在你的skill的前言部分

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
dependencies: [leyline:usage-logging]
**验证：** 运行带`--help`参数的命令验证功能是否可用。

标准集成流程：
1. 为你的服务初始化日志器
2. 操作完成后记录日志
3. 查询数据用于分析和调试

Log Storage

日志存储

Default location: 
~/.claude/leyline/usage/{service}.jsonl
bash
undefined
默认存储位置：
~/.claude/leyline/usage/{service}.jsonl
bash
undefined

View recent logs

查看最近日志

tail -20 ~/.claude/leyline/usage/my-service.jsonl | jq .
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.
grep "2025-12-05" ~/.claude/leyline/usage/my-service.jsonl
**验证：** 运行带`--help`参数的命令验证功能是否可用。

Detailed Resources

详细资源

  • Session Patterns: See 
    modules/session-patterns.md
    for session management
  • Log Formats: See 
    modules/log-formats.md
    for structured formats
  • 会话模式： 查看
    modules/session-patterns.md
    了解会话管理相关内容
  • 日志格式： 查看
    modules/log-formats.md
    了解结构化格式相关内容

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
找不到命令 确保所有依赖已安装且已添加到PATH中
权限错误 检查文件权限，使用合适的权限运行
异常行为 添加
--verbose
参数启用详细日志排查