Metadata-Version: 2.4
Name: logs-spectre
Version: 0.1.3
Summary: Stream log files and extract context/blocks around spanId matches.
Author: spectre contributors
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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:

``` bash
pip install logs-spectre
```

After installation, use the CLI command:

``` bash
spectre
```

------------------------------------------------------------------------

## Quick Start

Search for a span ID in a log file:

``` bash
spectre --logfile app.log --spanid F76281848BD8288C
```

Show the full logical block (including stack traces):

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

Write results to a file:

``` bash
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
