LogSentry — 日志质量与可观测性分析工具

LogSentry 扫描代码库，识别日志反模式、缺失的结构化日志、日志输出中敏感数据泄露、日志级别不一致、缺失关联 ID（correlation IDs）以及日志注入漏洞。它基于正则表达式匹配 6 大类共 90 个专用于日志检测的规则，并通过 lefthook 实现 Git 钩子集成，最终生成含可操作修复建议的 Markdown 报告。100% 本地运行，零遥测（Zero telemetry）。

命令

免费版（无需许可证）

logsentry scan [文件|目录]

对指定文件或目录执行一次性日志质量扫描。

执行方式：

bash "/scripts/dispatcher.sh" --path [目标路径]

功能说明：

1. 接受文件路径或目录路径（默认为当前目录）
2. 自动发现所有源码文件（跳过 .git、node_modules、二进制文件、图片、.min.js 等）
3. 对每个文件应用 30 条日志质量检测规则（免费版限制）
4. 为每个文件及整体计算日志质量得分（0–100 分）
5. 评分等级：A（90–100）、B（80–89）、C（70–79）、D（60–69）、F（低于 60）
6. 输出结果包含：文件路径、行号、检查项 ID、严重程度、描述、修复建议
7. 若得分为 ≥70，退出码为 0；若日志质量较差（得分 <70），退出码为 1
8. 免费版仅启用前 30 条规则（SL + LL 类别）

典型使用场景示例：

• “扫描我的代码中是否存在日志问题” → 执行 logsentry scan .
• “检查该文件是否存在日志反模式” → 执行 logsentry scan src/server.ts
• “查找日志中是否包含敏感数据” → 执行 logsentry scan src/
• “审计我项目的日志质量” → 执行 logsentry scan .
• “检查是否存在日志注入漏洞” → 执行 logsentry scan .

专业版（$19/用户/月 —— 需配置 LOGSENTRY_LICENSE_KEY）

logsentry scan --tier pro [文件|目录]

增强型扫描，覆盖结构化日志、日志级别、敏感数据与日志注入共 60 条规则。

执行方式：

bash "/scripts/dispatcher.sh" --path [目标路径] --tier pro

功能说明：

1. 验证专业版及以上许可证有效性
2. 执行全部 60 条日志检测规则（SL、LL、SD、LI 类别）
3. 检测日志中泄露的敏感数据（如密码、令牌、PII）
4. 识别日志注入漏洞
5. 按类别提供完整检测结果分解报告

logsentry scan --format json [目录]

生成 JSON 格式输出，适用于 CI/CD 集成。

bash "/scripts/dispatcher.sh" --path [目录] --format json

logsentry scan --format html [目录]

生成 HTML 格式报告，支持浏览器查看。

bash "/scripts/dispatcher.sh" --path [目录] --format html

logsentry scan --category SD [目录]

限定扫描范围至特定检查类别（SL、LL、SD、LI、CI、OB）。

bash "/scripts/dispatcher.sh" --path [目录] --category SD

团队版（$39/用户/月 —— 需配置具备团队版权限的 LOGSENTRY_LICENSE_KEY）

logsentry scan --tier team [目录]

全量扫描，覆盖全部 6 大类共 90 条规则，包括关联 ID 与可观测性检查。

执行方式：

bash "/scripts/dispatcher.sh" --path [目录] --tier team

功能说明：

1. 验证团队版及以上许可证有效性
2. 执行全部 90 条规则（覆盖 SL、LL、SD、LI、CI、OB 六大类别）
3. 包含关联性与上下文检查（如缺失请求 ID、Trace ID）
4. 包含可观测性检查（如缺失指标上报、健康检查日志、审计事件、错误率追踪）
5. 按类别提供完整结果分解，并附带各文件级明细

logsentry scan --verbose [目录]

详细模式输出，展示每条匹配行及其对应规则的完整细节。

bash "/scripts/dispatcher.sh" --path [目录] --verbose

logsentry status

显示许可证状态与当前配置信息。

bash "/scripts/dispatcher.sh" status

检查类别

LogSentry 在 6 大类别中共检测 90 种日志反模式：

按版本划分的规则访问权限

评分机制

LogSentry 采用扣分制，基准分为 100（满分）：

评分等级标准

• 通过阈值：70 分（即 C 级或以上）
• 退出码 0 = 通过（得分 ≥ 70）
• 退出码 1 = 不通过（得分 < 70，适用于 CI/CD 集成）

配置

用户可在 ~/.openclaw/openclaw.json 中配置 LogSentry：

{
  "skills": {
    "entries": {
      "logsentry": {
        "enabled": true,
        "apiKey": "YOUR_LICENSE_KEY_HERE",
        "config": {
          "severityThreshold": "medium",
          "ignorePatterns": ["**/test/**", "**/fixtures/**", "**/*.test.*"],
          "ignoreChecks": [],
          "reportFormat": "text"
        }
      }
    }
  }
}

重要说明

• 免费版开箱即用，无需任何配置
• 全部扫描均在本地完成 —— 代码不会上传至任何外部服务器
• 许可证校验离线进行 —— 不发起任何“回传”（phone-home）或网络请求
• 纯正则匹配实现 —— 不依赖 AST 解析，除 bash 外无其他外部依赖
• 支持单次扫描全部文件类型
• Git 钩子依赖 lefthook，需提前安装（参见上方安装说明）
• 退出码定义：0 = 通过（得分 ≥ 70），1 = 不通过（用于 CI/CD 集成）
• 输出格式：text（默认）、json、html

错误处理

• 若未安装 lefthook 而用户尝试启用钩子，提示用户安装
• 若许可证密钥无效或已过期，显示清晰错误信息并附链接 https://logsentry.pages.dev/renew
• 若目标为二进制文件，自动跳过且不发出警告
• 若目标路径下未发现可扫描文件，返回“干净扫描”提示信息
• 若 --category 参数指定非法类别，列出所有有效类别供参考

适用场景

用户可能提出如下请求：

• “扫描我的代码中是否存在日志问题”
• “检查我的日志质量”
• “查找日志中是否包含敏感数据”
• “检测日志注入漏洞”
• “是否有密码被记录到日志中？”
• “检查是否缺失结构化日志”
• “审计我的可观测性实践”
• “查找日志级别不一致的问题”
• “检查是否缺失关联 ID”
• “扫描日志反模式”
• “执行一次日志质量审计”
• “生成日志质量报告”
• “检查用户输入是否被不安全地记录到日志中”
• “查找应替换为 logger 调用的 print 语句”
• “检查我的代码是否存在日志注入风险”