日志记录Hook：操作日志自动化 - 学习笔记-Hooks案例

一、日志记录Hook的设计

日志记录Hook是Claude Code Hook系统中最为实用的基础能力之一，它的核心目标是自动记录Claude Code在运行过程中产生的所有操作轨迹，形成可审计、可追溯、可分析的日志文件。在实际开发中，无论是团队协作需要审计所有操作变更，还是个人开发者需要回溯之前的调试过程，一套完善的日志记录系统都能带来极大的便利。

本案例展示如何构建一套完整的日志记录方案，涵盖从工具调用的详细记录到用户提示的日志管理，再到日志文件的轮转维护和分析辅助。整个方案基于Claude Code提供的after:tool:*和after:user-prompt-submit两个核心Hook事件，辅以配套的日志管理脚本和查询工具。

核心设计目标：全面、安全、可维护。全面意味着覆盖所有操作类型；安全意味着敏感信息脱敏；可维护意味着日志文件自动轮转和清理，不会无限增长。

全面记录

覆盖所有工具调用和用户提示，包括时间戳、参数、结果、耗时等信息

安全可控

敏感信息自动脱敏，不记录完整提示内容，保护隐私和数据安全

可维护性

自动日志轮转、归档和清理，支持按大小和时间分割文件

可分析性

结构化日志格式（JSON/CSV），配套查询和分析工具

二、工具调用日志Hook（after:tool:*）

工具调用日志是整个日志记录系统的核心组成部分。通过监听after:tool:*事件，每次Claude Code调用任何工具（如Read、Write、Bash、Edit等）之后，Hook脚本都会被执行，从而记录下本次调用的完整信息。

记录的信息维度

每条工具调用日志包含五大信息维度：时间维度记录操作发生的精确时间和执行耗时；身份维度记录调用的工具名称；输入维度记录传入的参数内容（经过脱敏处理）；输出维度记录调用结果（成功或失败及返回数据）；状态维度记录调用是否成功以及错误消息。

日志格式示例（JSON）

{
  "timestamp": "2026-05-08T10:15:30.123Z",
  "hook": "after:tool:Read",
  "tool": "Read",
  "params": {
    "file_path": "/path/to/project/src/main.js"
  },
  "result": {
    "success": true,
    "lines": 245,
    "size_bytes": 12890
  },
  "duration_ms": 320,
  "session_id": "sess_abc123def456"
}

敏感信息脱敏

在记录日志时，必须对可能包含敏感信息的参数进行脱敏处理。常见的脱敏场景包括：文件路径中的用户名信息、API密钥或Token参数、数据库连接字符串中的密码、环境变量中的敏感配置等。脱敏策略采用正则匹配替换，将敏感内容替换为***REDACTED***标记，在保留日志结构完整性的同时确保信息安全。

安全警示：永远不要在日志中记录完整的文件内容、API密钥、密码或用户隐私数据。建议在Hook脚本中定义一个敏感参数列表，匹配到的参数值自动脱敏。

错误状态记录

当工具调用失败时，日志中会额外记录错误状态码和错误消息，帮助开发者快速定位问题。错误日志包含完整的错误堆栈信息（同样经过脱敏处理），并且会以ERROR级别标记，便于后续的日志过滤和告警。

{
  "timestamp": "2026-05-08T10:16:45.678Z",
  "hook": "after:tool:Write",
  "tool": "Write",
  "params": {
    "file_path": "/path/to/readonly/file.txt"
  },
  "result": {
    "success": false,
    "error": {
      "code": "EPERM",
      "message": "Permission denied",
      "stack": "Error: EPERM: operation not permitted, open '...'"
    }
  },
  "duration_ms": 15,
  "session_id": "sess_abc123def456",
  "log_level": "ERROR"
}

三、用户提示日志Hook（after:user-prompt-submit）

除了工具调用日志，记录用户与Claude Code之间的交互提示同样重要。通过监听after:user-prompt-submit事件，可以记录每次用户提交提示和AI生成回复的概要信息，为后续的对话回溯和使用模式分析提供数据基础。

记录内容设计

考虑到隐私保护的重要性，用户提示日志采用摘要记录策略：不记录用户输入的完整提示内容，而是提取前N个字符作为摘要，同时标记提示的类型（如代码编写、文件操作、问题咨询等）；AI回复同样只记录前N个字符的摘要和总长度，不保存完整回复。同时每条日志关联会话ID，使得同一会话中的多次交互可以串联起来形成完整的使用轨迹。

{
  "timestamp": "2026-05-08T10:15:00.000Z",
  "hook": "after:user-prompt-submit",
  "session_id": "sess_abc123def456",
  "prompt_summary": "请帮我编写一个React Hook用于日志记录...(前100字)",
  "prompt_type": "code_generation",
  "prompt_length_chars": 156,
  "response_summary": "以下是一个完整的日志记录Hook实现...(前100字)",
  "response_length_chars": 2840,
  "turn_number": 7
}

隐私设计原则：默认只记录提示的前100个字符作为摘要，不保存完整内容。如果需要在特定场景下保存完整记录，应通过配置项显式开启，并确保符合数据保护合规要求。

会话追踪机制

每次Claude Code启动时生成一个唯一的会话ID（session_id），该ID在整个会话生命周期内保持不变。所有工具调用日志和用户提示日志都会携带这个会话ID，从而将分散的日志条目关联到具体的会话上下文。当需要回溯某次完整的操作过程时，只需按会话ID过滤，即可获得该会话中所有操作的时序列表。

会话追踪的价值：在调试复杂问题时，可以精确定位到某次会话中所有操作的时间线，理解Claude Code的思考过程和操作顺序，大幅提升排查效率。

四、日志文件管理

随着Claude Code的持续使用，日志文件会不断增长。如果没有合理的文件管理策略，日志文件将很快消耗大量磁盘空间，同时也会降低日志查询的效率。因此，一套完整的日志文件管理方案必不可少。

日志格式设计

系统同时支持两种日志格式，以满足不同的使用场景：JSON格式是主格式，每条日志为一行JSON对象（JSON Lines格式），便于程序化解析和处理，可以直接导入到ELK、Splunk等日志分析平台；CSV格式作为辅助格式，将关键字段以表格形式输出，方便使用Excel或Numbers直接打开查看和筛选。

# JSON Lines 格式（每条日志独立一行）
{"timestamp":"2026-05-08T10:15:30Z","tool":"Read","duration_ms":320,"success":true}
{"timestamp":"2026-05-08T10:16:00Z","tool":"Bash","duration_ms":1500,"success":true}
{"timestamp":"2026-05-08T10:16:45Z","tool":"Write","duration_ms":15,"success":false}

# CSV 格式（带表头）
timestamp,tool,params,success,duration_ms,error
2026-05-08T10:15:30Z,Read,{file_path:main.js},true,320,
2026-05-08T10:16:45Z,Write,{file_path:readonly.txt},false,15,EPERM

日志轮转策略

日志轮转是防止日志文件无限增长的关键机制。系统支持两种轮转触发条件：按文件大小分割（默认10MB），当当前日志文件达到阈值时自动创建新文件，文件名追加序号；按时间分割（默认每天），无论文件大小如何，每天切换一个新的日志文件。两种策略可以同时启用，以先触发的条件为准。轮转后的旧日志文件按照配置的保留天数（默认30天）自动清理，超过保留期限的文件会被安全删除。

# 日志轮转配置示例
{
  "log_dir": "~/.claude/logs",
  "rotation": {
    "max_size_mb": 10,
    "interval_days": 1,
    "retention_days": 30,
    "compress": true
  },
  "formats": ["json", "csv"],
  "redact_fields": ["api_key", "password", "token"]
}

日志归档流程

轮转出的旧日志文件被自动移动到归档目录（~/.claude/logs/archive/），并按照YYYY/MM/的目录结构组织，便于按时间范围浏览。归档文件默认启用GZip压缩，可以节省约80%的存储空间。归档目录同样受保留策略管理，超期文件自动清理。

最佳实践：建议将日志目录链接到云存储或NAS的同步目录，实现日志的异地备份。同时配合日志分析平台（如ELK Stack）实时摄入日志数据，构建完整的操作审计和监控体系。

五、日志查询和分析辅助

记录日志只是第一步，如何高效地查询和分析日志数据才是发挥日志价值的关键。系统配套提供了简单易用的日志查询命令行工具，支持多种过滤条件和统计功能。

基本查询命令

# 查看最近50条日志
logctl tail -n 50

# 按时间范围过滤
logctl query --from "2026-05-08" --to "2026-05-09"

# 按工具类型过滤
logctl query --tool Bash --tool Write

# 只查看失败的操作
logctl query --status error

# 统计各工具使用频率
logctl stats --by tool --period daily

# 生成操作报告（Markdown格式）
logctl report --output report.md --period weekly

多维过滤能力

查询工具支持同时组合多个过滤条件：按时间范围（--from / --to）、按工具名称（--tool，支持多次指定和通配符）、按执行状态（--status：success/error/all）、按执行耗时（--min-duration和--max-duration，单位毫秒）、按会话ID（--session）。所有过滤条件之间为"与"关系，可以精确定位到目标日志条目。

统计和报告功能

除了基本的查询过滤，日志分析工具还提供统计和报告生成能力。可以统计指定时间范围内各工具的使用次数、平均耗时、失败率等指标，并以表格或图表形式输出。支持生成周报和月报格式的操作报告，包含：工具调用量趋势、Top-N耗时操作排行、失败操作汇总、各会话操作量分布等维度。报告输出为Markdown格式，可以直接用于团队周报或个人总结。

典型应用场景：团队Leader可以查看成员的Claude Code使用报告，了解工具的使用频率和模式；开发者可以分析自己的操作习惯，发现效率瓶颈；运维人员可以通过错误日志趋势分析系统稳定性。

查询维度	命令参数	说明
时间范围	--from / --to	ISO 8601时间格式，支持日期或完整时间戳
工具类型	--tool	支持多次指定，如 --tool Read --tool Bash
执行状态	--status	success / error / all（默认all）
执行耗时	--min-duration / --max-duration	单位毫秒，筛选慢调用或快速调用
会话ID	--session	精确匹配会话ID，查看单次会话完整操作轨迹

未来扩展方向

日志查询系统预留了扩展接口，未来可以接入可视化仪表盘（如Grafana）、实时告警（如操作失败率超过阈值时发送通知）、操作回放（根据日志重建某次会话的完整操作序列）等高级功能，将日志数据的价值进一步放大。