用 CLI 安全搜索日志

---
name: search-logs-workflow
description: "先限定时间、服务、文件和模式，再只收集解释事故所需的日志行。"
---

# 搜索应用日志

## 适用目标

找到相关错误序列，不暴露无关用户、密钥，也不读取无限生产日志流。

## 证据边界

- 工具状态分别标注 `docs-verified` 与真实独立执行；二者不能互换。
- 当前注册表没有记录某次工具执行具体由哪个 Agent 完成，因此不能把“兼容 Agent”称为“已测试 Agent”。
- 执行前重新核对目标账户、环境、版本与官方文档。
- 不自动执行 R2、R3 或任何标记为需要确认的步骤；必须在执行前获得明确批准。

## 推荐工具、安装与认证

- **ripgrep**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 15.1.0）
  - 安装：`brew install ripgrep`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。
- **Datadog Pup CLI**（证据：`docs-verified`，文档检查：`2026-07-10`，未记录独立执行版本）
  - 安装：`brew tap datadog-labs/pack && brew install datadog-labs/pack/pup`
  - 认证：OAuth2 PKCE, access token, API and application keys
  - 最小权限：优先使用 OAuth Scope 或 --read-only；无人值守且可写的会话不得设置 DD_AUTO_APPROVE。
- **jq**（证据：`verified`，文档检查：`2026-07-10`，已记录独立测试版本 jq-1.7.1-apple）
  - 安装：`brew install jq`
  - 认证：基础操作无需认证
  - 最小权限：无需服务凭据；仍应把文件系统和网络访问限制在任务范围内。

## 输入合同

- 事故时间窗口
- 服务或文件范围
- Request 或 Trace ID
- 脱敏规则

## 输出合同

- 带上下文的匹配事件
- 搜索命令
- 时间线摘要
- 证据缺口与下一步

## 安全工作流

1. **定义窄查询** — 从时间、服务、Request ID 或精确错误 token 和有限文件开始。
   - 输入: 事故线索和日志位置
   - 输出: 可审查搜索范围
   - 风险: `read-only`
   - 命令: `rg -n -F "request-id" logs/ --glob "*.log"`
2. **收集上下文** — 只增加有限上下文行或解析 JSON 字段，不倾倒全部日志。
   - 输入: 初始匹配
   - 输出: 相关事件序列
   - 风险: `read-only`
3. **脱敏并汇总** — 删除 Token 和个人数据，保留时间戳与 ID，并注明缺失证据。
   - 输入: 匹配日志窗口
   - 输出: 事故时间线与脱敏证据
   - 风险: `local-write`

## 必须先确认

- 查询生产可观测平台
- 扩大时间、服务、租户或环境范围
- 下载或把日志分享至获批位置之外

## 回滚

- 任务后删除临时原始日志导出
- 撤销临时可观测凭证
- 事故记录只保留必要的脱敏证据

## 官方来源

- [ripgrep guide](https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md) — 用于核对当前命令、认证、输出和操作边界。
- [Datadog Pup repository](https://github.com/DataDog/pup) — 用于核对当前命令、认证、输出和操作边界。
- [jq manual](https://jqlang.github.io/jq/manual/) — 用于核对当前命令、认证、输出和操作边界。