Search Logs Safely with a CLI

---
name: search-logs-workflow
description: "Constrain the time, service, file, and pattern first; then collect only the lines needed to explain the incident."
---

# Search application logs

## Intended outcome

Find a relevant error sequence without exposing unrelated users, secrets, or an unbounded production log stream.

## Evidence boundary

- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.

## Recommended tools, installation, and authentication

- **ripgrep** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version 15.1.0 recorded)
  - Install: `brew install ripgrep`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.
- **Datadog Pup CLI** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
  - Install: `brew tap datadog-labs/pack && brew install datadog-labs/pack/pup`
  - Authentication: OAuth2 PKCE, access token, API and application keys
  - Minimum permissions: Prefer OAuth scopes or --read-only; never set DD_AUTO_APPROVE for an unattended write-capable session.
- **jq** (evidence: `verified`, docs checked: `2026-07-10`, independently tested version jq-1.7.1-apple recorded)
  - Install: `brew install jq`
  - Authentication: not required for the base operation
  - Minimum permissions: No service credential is required; restrict filesystem and network access to the task.

## Input contract

- Incident time window
- service or file scope
- request or trace identifier
- redaction rules

## Output contract

- Matching events with context
- search command
- timeline summary
- gaps and next checks

## Safe workflow

1. **Define a narrow query** — Start with a timestamp, service, request ID, or exact error token and bounded files.
   - Input: Incident clue and log locations
   - Output: Reviewable search boundary
   - Risk: `read-only`
   - Command: `rg -n -F "request-id" logs/ --glob "*.log"`
2. **Collect context** — Add limited surrounding lines or parse JSON fields without dumping the full log set.
   - Input: Initial matches
   - Output: Relevant event sequence
   - Risk: `read-only`
3. **Redact and summarize** — Remove tokens and personal data, preserve timestamps and IDs, and note missing evidence.
   - Input: Matched log window
   - Output: Incident timeline and sanitized evidence
   - Risk: `local-write`

## Ask before proceeding

- Querying production observability systems
- Broadening the time, service, tenant, or environment scope
- Downloading or sharing logs outside the approved location

## Rollback

- Delete temporary raw log exports after the task
- Revoke temporary observability credentials
- Keep only the sanitized evidence required for the incident record

## Official sources

- [ripgrep guide](https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md) — Project guide for search behavior, filters, file types, and output controls.
- [Datadog Pup repository](https://github.com/DataDog/pup) — Upstream command and authentication documentation for the Pup CLI.
- [jq manual](https://jqlang.github.io/jq/manual/) — Official filters, input modes, exit status, and JSON transformation reference.