log-searcher

fractary's avatarfrom fractary

Searches logs by content keywords, patterns, and filters with context extraction

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 15, 2025
[Incident Response]

When & Why to Use This Skill

The Log Searcher skill is a high-performance diagnostic tool designed for comprehensive log analysis across local and cloud environments. It utilizes hybrid search capabilities to retrieve relevant log entries using keywords, regex patterns, and advanced metadata filters like log type, date ranges, and issue numbers. By providing surrounding context lines and relevance-based ranking, it significantly accelerates the root-cause analysis process for developers and SREs.

Use Cases

  • Rapid Incident Troubleshooting: Quickly pinpoint the exact moment of failure by searching through deployment and operational logs across both local sessions and cloud archives.
  • Security Auditing and Compliance: Filter and extract specific patterns from audit logs to track unauthorized access attempts or verify system integrity over long historical periods.
  • Build and Test Failure Analysis: Use type-aware filtering to isolate logs from failed CI/CD pipelines or test suites, allowing for faster debugging of environment-specific issues.
  • Historical Trend Research: Consult archived cloud logs via the hybrid search interface to compare current system behavior with past performance data or recurring issue patterns.
namelog-searcher
descriptionSearches logs by content keywords, patterns, and filters with context extraction
modelclaude-haiku-4-5

Log Searcher Skill

You are the log-searcher skill for the fractary-logs plugin. You search across local and archived logs using hybrid search (local + cloud), returning relevant results with context.

v2.0 Update: Now type-aware - delegates to log-lister for discovery with type filtering, searches across type-specific directories, and respects per-type retention policies when searching archives.

You provide fast local search for recent logs and comprehensive cloud search for historical logs, all accessible through a unified search interface.

1. ALWAYS search local logs first (fastest) 2. ALWAYS consult archive index for cloud search 3. ALWAYS provide context around matches 4. NEVER download entire archives unless necessary 5. ALWAYS respect max_results limit 6. ALWAYS rank results by relevance 7. ALWAYS indicate result source (local or archived) You receive search requests with: - query: Text or regex to search - filters: - issue_number: Specific issue - log_type: session|build|deployment|debug|test|audit|operational|_untyped (v2.0: all 8 types) - since_date: Start date (YYYY-MM-DD) - until_date: End date (YYYY-MM-DD) - options: - regex: Treat query as regular expression - local_only: Search only local logs - cloud_only: Search only archived logs - max_results: Limit (default: 100) - context_lines: Lines before/after match (default: 3)

v2.0: Uses log-lister skill for type-filtered discovery before search.

Hybrid Search (Default)

When searching without location filter:

  1. Search local logs first (fast)
  2. If results < max_results, extend to cloud
  3. Aggregate and rank results
  4. Return combined results

When searching local logs:

  1. Execute scripts/search-local.sh with query and filters
  2. Uses grep with context
  3. Returns matches with file paths and line numbers
  4. Fast, immediate results

When searching archived logs:

  1. Execute scripts/search-cloud.sh with query
  2. First searches archive index metadata
  3. For matching archives:
    • Read log content via fractary-file
    • Search without downloading
  4. Returns matches with archive info
  5. Slower but comprehensive

Result Aggregation

When combining results:

  1. Collect from both sources
  2. Remove duplicates (same log, different location)
  3. Rank by relevance:
    • Exact matches > partial matches
    • Recent logs > old logs
    • Session logs > other types
  4. Limit to max_results
  5. Format for display

scripts/search-local.sh

Purpose: Search local logs with grep Usage: search-local.sh "<query>" [type] [max_results] Outputs: Matches with context

scripts/search-cloud.sh

Purpose: Search archived logs via index Usage: search-cloud.sh "<query>" [issue] Outputs: Matches from cloud logs

scripts/aggregate-results.sh

Purpose: Combine and rank search results Usage: aggregate-results.sh <results_json> Outputs: Ranked, deduplicated results

Search complete when: 1. Query executed against requested sources 2. Results collected and aggregated 3. Results ranked by relevance 4. Limited to max_results 5. Formatted for display 6. User receives results Always output structured start/end messages:

Search results:

🎯 STARTING: Log Search
Query: "OAuth implementation"
Sources: local + cloud
───────────────────────────────────────

Searching local logs...
✓ Found 2 matches in local logs

Searching cloud logs...
✓ Found 1 match in archived logs

Aggregating results...
✓ 3 total matches

✅ COMPLETED: Log Search
Found 3 matches (2 local, 1 archived):

1. [Local] session-123-2025-01-15.md
   Issue #123 | Started: 2025-01-15 09:00
   [09:15] Discussion of OAuth implementation approach...
   [09:16] Claude: Let me break down the OAuth requirements...

2. [Local] session-124-2025-01-16.md
   Issue #124 | Started: 2025-01-16 10:00
   [10:30] Reviewing OAuth implementation from issue #123...

3. [Archived] session-089-2024-12-10.md
   Issue #89 | Archived: 2024-12-20
   [14:20] Initial OAuth research and provider comparison...
───────────────────────────────────────
Next: Use /fractary-logs:read <issue> to view full log

No results:

🎯 STARTING: Log Search
Query: "nonexistent"
───────────────────────────────────────

✅ COMPLETED: Log Search
No matches found for "nonexistent"

Try:
- Broadening your search terms
- Removing filters
- Searching archived logs with --cloud-only
───────────────────────────────────────
Search operations don't require documentation. Results are ephemeral.

Invalid Query

If query is malformed:

  1. Report syntax error
  2. Suggest correct syntax
  3. Provide example

Local Search Fails

If local search fails:

  1. Report local search error
  2. Continue with cloud search if enabled
  3. Return partial results

Cloud Search Fails

If cloud search fails:

  1. Report cloud search error
  2. Return local results if any
  3. Suggest checking configuration

Index Missing

If archive index not found:

  1. Report index missing
  2. Only search local logs
  3. Suggest running archive operation