Metadata-Version: 2.4
Name: logs-spectre
Version: 0.1.1
Summary: Stream log files and extract context/blocks around spanId matches.
Author-email: BoubkerElmaayouf <boubkerelmaayouf@gmail.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# spectre

A small CLI tool that **finds a span id in a large log file** and prints either:

- **context** around each match (like `grep -C`), or
- the **full logical block** for the matched log event (including multiline stack traces)

This is useful for troubleshooting and correlation workflows (e.g., following a Dynatrace span/trace through services).

## Features

- Python **3.11+**
- Streams files **line-by-line** (safe for large logs)
- Fixed-size ring buffer (`deque`) for **before-context**
- Supported formats (auto-detected or forced):
  - **KV / plain text** (`spanId=...`, `span_id=...`, `span-id=...`, `spanid=...`)
  - **JSON-per-line** (extracts `spanId`, `span_id`, `spanid`, `span-id`, etc.)
  - **W3C traceparent** (`traceparent="00-<trace-id>-<parent-id>-<flags>"`)  
    The **parent-id (16 hex chars)** is treated as the span id for matching.

## Install (local)

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

Run:

```bash
spectre --logfile examples/sample_kv.log --spanid F76281848BD8288C --mode block --context 20
```

## Install + Run (Docker)

Build:

```bash
docker build -t spectre .
```

Run (mount current folder as `/work`):

```bash
docker run --rm -v "$PWD:/work" spectre \
  --logfile /work/examples/sample_kv.log \
  --spanid F76281848BD8288C \
  --mode block \
  --context 20
```

## Usage

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

Options:

- `--help`: print this help message
- `--context N` : number of lines before/after match (default: 20)
- `--mode {context,block}` :
  - `context`: print `N` before + match + `N` after (like `grep -C`)
  - `block`: print the full “logical block” (including multiline stack traces) and also includes `--context` lines before the match
- `--output PATH` : write to a file (default: stdout)
- `--format {auto,kv,json,traceparent}` : force parsing mode (default: auto)
- `--ignore-case` (default): case-insensitive matching
- `--case-sensitive`: disable ignore-case
- `--interactive`: prompt interactively for missing arguments or this is the default mode if no arguments are provided

### Examples

#### KV / plain text log

```bash
spectre --logfile examples/sample_kv.log --spanid F76281848BD8288C --mode context --context 10
```

#### JSON-per-line log

```bash
spectre --logfile examples/sample_json.log --spanid a1b2c3d4e5f60718 --format json --mode block
```

#### traceparent log

In W3C `traceparent`, the third field is the **parent-id**, which is 16 hex chars and corresponds to a span id:

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

```bash
spectre --logfile examples/sample_traceparent.log --spanid 6f35a0c9d2d3b4a1 --format traceparent --mode block
```

## Output format

For each occurrence:

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

If no matches are found, the tool prints `NOT FOUND` and exits with code **1**.
If matches are found, it exits with code **0**.
File errors (not found / permission) exit with code **2**.

## Performance notes

- The scanner **streams** the log file line-by-line.
- Only a fixed-size `deque(maxlen=context)` is kept for “before” lines.
- Output is written in a streaming way (no huge strings built in memory).

## Standalone Build (No Python Required)

You can package `spectre` as a single executable using **PyInstaller**.  
This allows users to run the tool **without installing Python**.

> ⚠️ Important: You must build on each target OS (Windows builds Windows exe, Linux builds Linux binary, macOS builds macOS binary).

---

### 1) Local build on Windows

In **PowerShell**:

```powershell
py -3.14 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
python -m pip install -e .
python -m pip install pyinstaller

pyinstaller --onefile --console --name spectre -m spectre.cli
```

Output:

```
dist\spectre.exe
```

Test:

```powershell
.\dist\spectre.exe --help
```

If you need to include the `examples/` folder inside the executable:

```powershell
pyinstaller --onefile --console --name spectre -m spectre.cli --add-data "examples;examples"
```

---

### 2) Local build on Linux (machine or VM)

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
python -m pip install pyinstaller

pyinstaller --onefile --console --name spectre -m spectre.cli
```

Output:

```
dist/spectre
```

Test:

```bash
./dist/spectre --help
```

Include `examples/`:

```bash
pyinstaller --onefile --console --name spectre -m spectre.cli --add-data "examples:examples"
```

---

### 3) Local build on macOS (requires a Mac)

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
python -m pip install pyinstaller

pyinstaller --onefile --console --name spectre -m spectre.cli
```

Output:

```
dist/spectre
```

Test:

```bash
./dist/spectre --help
```

---

## Distribution

You can publish the generated binaries:

- `spectre.exe` → Windows
- `spectre` → Linux
- `spectre` → macOS

For clarity when distributing, you may rename them to:

- `spectre-windows.exe`
- `spectre-linux`
- `spectre-macos`

Users can then download the correct binary for their OS and run it directly.

---

## Notes

- macOS may show a security warning for unsigned binaries.
- Cross-compilation is not recommended; build on each OS.
- If PyInstaller has compatibility issues with the latest Python version, building with Python 3.13 is generally safe and reliable.