logs-spectre 0.1.3

Stream log files and extract context/blocks around spanId matches.

logs-spectre

                              __                  
  ____________   ____   _____/  |________   ____  
 /  ___/\____ \_/ __ \_/ ___\   __\_  __ \_/ __ \ 
 \___ \ |  |_> >  ___/\  \___|  |  |  | \/\  ___/ 
/____  >|   __/ \___  >\___  >__|  |__|    \___  >
     \/ |__|        \/     \/                  \/ 

logs-spectre or spectre is a lightweight command-line tool that searches large log files for a given span ID and extracts either:

• Context around the match (like grep -C), or\
• The full logical log block (including multiline stack traces)

It is designed for troubleshooting distributed systems and observability workflows, especially when following traces across services.

---

Why logs-spectre?

When debugging production systems, you often need to:

• Follow a single request across multiple services
• Extract stack traces tied to a specific span
• Search very large log files safely
• Avoid loading entire files into memory

logs-spectre solves this efficiently with streaming, zero external dependencies, and a simple CLI interface.

---

Installation

Install from PyPI:

pip install logs-spectre

After installation, use the CLI command:

spectre

---

Quick Start

Search for a span ID in a log file:

spectre --logfile app.log --spanid F76281848BD8288C

Show the full logical block (including stack traces):

spectre --logfile app.log --spanid F76281848BD8288C --mode block

Write results to a file:

spectre --logfile app.log --spanid F76281848BD8288C --output result.log

---

Supported Log Formats

1. Key-Value / Plain Text Logs

Supports variations like:

• spanId=...
• span_id=...
• span-id=...
• spanid=...

---

2. JSON Logs (one entry per line)

Extracts span IDs from fields such as:

• spanId
• span_id
• spanid
• span-id

---

3. W3C traceparent Format

Example:

traceparent="00-<trace-id>-<parent-id>-<flags>"

The parent-id (16 hex characters) is treated as the span ID.

---

Usage

spectre --logfile PATH --spanid VALUE [options]

Required Arguments

• --logfile PATH --- Path to the log file\
• --spanid VALUE --- Span ID to search for

Optional Arguments

• --context N --- Number of lines before and after match (default: 20)\
• --mode {context,block}
  • context → N lines before + match + N lines after\
  • block → Full logical block including multiline stack traces\
• --output PATH --- Write results to a file instead of stdout\
• --format {auto,kv,json,traceparent} --- Force format detection (default: auto)\
• --ignore-case (default) --- Case-insensitive matching\
• --case-sensitive --- Enable case-sensitive matching\
• --interactive --- Prompt for missing arguments interactively

---

Output Format

For each match:

===== MATCH <index> START =====
line: <file line number>
spanId: <matching span id>
<extracted lines...>
===== MATCH <index> END =====

---

Exit Codes

• 0 → Match found\
• 1 → No match found\
• 2 → File error (not found / permission issue)

---

Performance

• Streams files line-by-line (safe for very large logs)
• Uses a fixed-size ring buffer for context lines
• Avoids loading entire files into memory
• Dependency-free runtime

---

Requirements

• Python 3.11+

---

License

MIT License