logs-spectre 0.1.0

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

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)

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

Run:

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

Install + Run (Docker)

Build:

docker build -t spectre .

Run (mount current folder as /work):

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

Usage

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

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

JSON-per-line log

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>"

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:

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:

.\dist\spectre.exe --help

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

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

---

2) Local build on Linux (machine or VM)

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:

./dist/spectre --help

Include examples/:

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

---

3) Local build on macOS (requires a Mac)

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:

./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.