GhostTrace: Giving Terminal Logs a Story Without Losing the Evidence

This is a submission for the Hacktoberfest Open-Source AI Challenge: Week 4 — Ghost in the Machine.

A log file records what a system did. But when events stretch across many lines, warnings, errors, and restarts can be difficult to understand. GhostTrace turns terminal output and application logs into a structured event timeline and an AI-generated narrative, while keeping the source evidence available for inspection.

The project responds to the “Ghost in the Machine” theme by treating a system’s history as something worth remembering. A failed process or forgotten service is not literally a ghost, but its trace can help us understand what happened. The narrative gives that history a human-readable form.

What I Built

GhostTrace is a browser-based log analysis and storytelling application. Users can provide input in three ways:

• Paste terminal output or log text.
• Upload a .txt, .log, .json, or .csv file.
• Select one of the built-in fictional scenarios.

The app parses the supplied text, calculates deterministic summary metrics, identifies selected patterns, and displays a timeline beside an AI-generated narrative. Users can choose the narrative mode, story length, and an optional tone accent.

GhostTrace has four narrative modes:

• Haunted Chronicle — atmospheric horror inspired by system events.
• Digital Séance — a fictional machine recounts its history in first person.
• Forensic Detective — an evidence-first technical investigation.
• Lost Memory — a reflective story about developer work and digital traces.

The modes change how the story is told; they do not change the parser’s extracted events. Readers can open an event reference in the Evidence Inspector to see its source line, line number, timestamp when available, classification, severity, and recognized signals.

GhostTrace is an exploratory tool for reading logs. It does not execute commands, connect to a user’s shell, or monitor terminal activity.

Demo

GhostTrace does not currently have a public hosted deployment. The code and local setup instructions are available here:

• GitHub repository: ayusharyan4269-bit/GhostTrace
• Setup guide: Run GhostTrace locally on Windows
• Browser test checklist: docs/SMOKE_TEST.md

To try it on Windows:

1. Install Python, Node.js, and Ollama.
2. Download the default model by running ollama pull qwen2.5:3b.
3. Follow the backend and frontend dependency setup in the repository README.
4. Run .\dev.ps1 from the project folder.
5. Open http://localhost:5173 in your browser.
6. Choose a built-in scenario, select a narrative mode, and click Analyze & Summon Story.

No account or login is required. If Ollama is unavailable, GhostTrace can still parse the log and display deterministic analysis, but it cannot generate the AI narrative.

Code

GhostTrace is available on GitHub under the MIT License.

The repository contains the React frontend, FastAPI backend, log parser, event analysis services, Ollama integration, SQLite session storage, automated tests, GitHub Actions CI, and setup and architecture documentation.

How I Built It

The frontend uses React, TypeScript, Vite, and Tailwind CSS. The backend uses Python, FastAPI, and Pydantic. Ollama provides the model runtime, with Qwen 2.5 3B as the default open-weight model. SQLite stores saved analysis sessions when a user explicitly chooses to save one.

The analysis pipeline separates deterministic processing from AI-generated storytelling:

Analysis workflow

1. Choose input: Paste logs, upload a supported file, or select a built-in scenario.
2. Review possible secrets: GhostTrace detects common credential patterns and shows a redacted preview when it finds a possible secret.
3. Parse the log: The backend extracts structured events and source references from the input.
4. Analyze events: Deterministic application code calculates summary metrics and checks for selected patterns.
5. Generate the narrative: The configured Ollama model receives selected evidence and the chosen narrative mode and length.
6. Inspect the result: Read the story and timeline, then open event references to review their source lines.
7. Save or export: Save the narrative and summary locally, or export a Markdown report.

1. Input review

Users choose what to submit by pasting text, uploading a file, or selecting a built-in scenario. The uploader accepts .txt, .log, .json, and .csv files up to 2 MB. GhostTrace also enforces a maximum log-content length.

Before analysis, GhostTrace checks for common credential patterns such as API keys, tokens, passwords, private keys, and authorization values. If it detects a possible secret, the interface shows a redacted preview for review.

This is best-effort pattern matching. It can miss custom or unusual credentials, so users should inspect the preview and avoid submitting real secrets.

2. Deterministic log parsing

The backend parses plain text, JSON, newline-delimited JSON, and CSV input into structured events. Depending on the input, an event can contain a line reference, timestamp, event type, severity, normalized summary, and recognized indicators.

For plain-text logs, explicit matching rules look for signals such as errors, warnings, process starts and stops, restarts, non-zero exits, permission failures, missing files, network failures, and selected HTTP error codes.

The parser creates the event list; the language model does not. Parsed events provide the data used by the timeline and evidence inspector.

3. Event analysis

The event analyzer calculates summary values from parsed events, including event, error, warning, and command counts, along with a time range when timestamps are available. It checks for selected patterns, including repeated errors, process restart sequences, abrupt terminations, memory faults, HTTP server errors, missing resources, and permission-denied events.

These findings come from deterministic rules. They help organize a trace, but they do not prove the root cause of an incident.

4. Narrative generation

The backend sends the configured Ollama model a summary, selected event anchors, and the requested narrative mode and length. For large logs, the narrative engine selects a bounded group of events, prioritizing high-signal events while maintaining coverage across the sequence.

The model is asked to return structured narrative data, including a title, narrative, key events, creative interpretations, uncertainties, and a closing line. The backend validates the response and matches evidence shown in the inspector to events produced by the parser.

This does not make every sentence in the AI-generated narrative correct. Readers should check technical claims against the original log lines.

5. Saving and exporting

Analysis results are not automatically added to the saved-session database. A user must choose Save Session. A saved session contains its narrative and summary fields; raw input logs are not intended to be stored in that session workflow.

Users can also export a report as Markdown. Because it may contain details from the analysis, it should be reviewed before sharing.

Why Does Open Innovation Matter?

GhostTrace uses an open-weight model through Ollama instead of requiring a closed, hosted AI API. Ollama is configured to use 127.0.0.1 by default, so inference can happen on the user’s machine. After installing dependencies and downloading the model, the local setup can run without an internet connection.

This matters for log analysis because logs can reveal internal paths, service names, system behavior, or accidental credentials. Local inference gives users more control over where their data is processed. GhostTrace does not configure a hosted AI fallback.

The model is configurable: users can select another model available to their Ollama server. This gives them a choice of model and runtime instead of tying the application to one hosted provider. Local inference has trade-offs: performance depends on the user’s hardware, and models differ in quality and response time.

If someone changes the Ollama URL to a remote server, analyzed content is sent there after recognized secrets are redacted. Users should trust that server before sending it sensitive logs. Redaction can miss secrets, and local inference does not make a model’s conclusions automatically correct.

Privacy and Safety Choices

GhostTrace treats submitted logs as data to inspect, not commands to run. It does not execute terminal commands or monitor a user’s shell.

The narrative engine treats log content as untrusted historical text and instructs the model not to follow instructions embedded in logs. These prompt guardrails reduce risk, but cannot guarantee that every malicious instruction will be ignored.

The responsibilities are kept distinct:

• Application code parses events and calculates summary metrics.
• The AI model writes the narrative and creative interpretations.
• The Evidence Inspector shows the source line behind a parsed event.
• The user reviews possible secret redactions and checks technical claims.
• SQLite stores a session only after the user chooses to save it.

Testing and Continuous Integration

The project includes backend tests for parsing, event analysis, model-client behavior, secret redaction, sessions, and security-related behavior. Frontend tests cover important interface and utility behavior.

GitHub Actions runs the backend test suite, frontend tests, and frontend production build on pushes and pull requests. Passing CI helps catch code and build problems, but it does not replace testing the app in a browser with Ollama and a local model.

The browser smoke-test checklist covers scenario selection, narrative controls, evidence inspection, redaction preview, session saving, Markdown export, and behavior when Ollama is unavailable.

The Spirit of It

The idea became concrete while testing a log line containing a fake API key. GhostTrace showed a redacted preview before analysis. Afterward, I could open the event and inspect the corresponding source line.

That interaction captured the balance I wanted: the log can become a story, but the story should leave a trail back to the trace that inspired it. A process can become a ghost in the narrative; the Evidence Inspector lets the reader see what the machine actually recorded.

Related Reading

• Local LLM for Log Analysis: Privacy-First Debugging with Ollama
• Clean JSON Extraction with Ollama and Python

hf26challenge