logX+ is an intelligent web application designed to dramatically simplify the process of log analysis. It acts as an expert assistant for developers, DevOps engineers, and support teams, transforming raw, often cryptic log files into a clear, structured, and actionable analysis.
The main use case is to rapidly accelerate debugging and incident resolution. Instead of manually sifting through thousands of lines of logs, a user can paste them into logX+ and instantly receive a summary, a visual breakdown of the root cause, a chart of error types, and a list of concrete recommendations.
This project is built for a hackathon to showcase a practical and powerful application of modern AI. It solves a real-world, persistent problem for developers by leveraging the advanced capabilities of the Google Gemini API, including a sophisticated client-side implementation of Retrieval-Augmented Generation (RAG).
Follow these instructions to set up and run the logX+ application on your local machine for development and testing.
- You must have Node.js (version 18 or newer) and
npminstalled. - You need a Google Gemini API Key. You can obtain one from Google AI Studio.
Navigate to the project's root directory in your terminal and run the following command to install all the necessary packages:
npm installThe application requires your Gemini API key to function.
-
In the root directory of the project, create a new file named
.env. -
Open the
.envfile and add your API key in the following format, replacingYOUR_API_KEY_HEREwith your actual secret key:VITE_GEMINI_API_KEY="YOUR_API_KEY_HERE"
Note: The
VITE_prefix is required for security reasons in Vite projects to expose variables to the client-side code.
Once the dependencies are installed and your API key is set, you can start the development server:
npm run devThis will launch the application. You can now open your web browser and navigate to the local address provided in your terminal (usually http://localhost:5173 or similar).
logX+ follows a seamless workflow from log input to actionable guidance, creating an intuitive user experience.
- Input: The user pastes raw log text or uploads a
.logfile into the application. - Retrieval (RAG): Before analyzing, the app searches its local knowledge base (stored in the browser's
localStorage). Using a TF-IDF and cosine similarity algorithm, it finds summaries and recommendations from the most relevant past incidents. This is the "Retrieval" step. - Augmentation & Generation (RAG): The retrieved historical context is combined with the new logs and sent to the Google Gemini API in a carefully structured prompt. This "Augmentation" provides the AI with valuable context, allowing it to "Generate" a more accurate and insightful analysis.
- Structured Analysis: The Gemini model processes the request and returns a structured JSON object containing:
- A concise, plain-English summary of the problem.
- A step-by-step root cause chain.
- A quantitative breakdown of error categories.
- A list of actionable, prioritized recommendations.
- Visualization: The UI renders this information in a user-friendly dashboard. The root cause chain is displayed as a clear timeline, and the error breakdown is shown as a pie chart.
- Interactive Assistance: The user can click on any recommendation to launch a "Step-by-Step Assistance" chat modal. This chat session is also powered by RAG; each question the user asks is augmented with historical context, providing guidance that is grounded in past solutions.
The project uses a modern, efficient, and self-contained tech stack that is perfect for a hackathon.
- Frontend: Built with React and TypeScript for a robust and maintainable user interface.
- Styling: Tailwind CSS is used for rapid, utility-first styling to create a clean and responsive design.
- AI Model: Google Gemini API (
@google/genai) is the core of the analysis engine. It's used for both the initial structured JSON analysis and the streaming conversational chat. - Retrieval-Augmented Generation (RAG):
- A sophisticated client-side RAG is implemented in
vectorDBService.ts. - It uses a TF-IDF (Term Frequency-Inverse Document Frequency) vectorizer and Cosine Similarity search to find the most relevant past incidents from the knowledge base.
- A sophisticated client-side RAG is implemented in
- Database: The browser's
localStorageacts as a client-side database. It stores the history of log analyses, creating a persistent knowledge base that the RAG system queries to improve future results. - Visualizations:
- Recharts: Used to render the interactive pie chart for the error breakdown.
- Custom React Components: A custom timeline component visually renders the root cause chain for clarity.
The application is architected as a fully client-side single-page application (SPA). This design is fast, efficient, and requires no backend infrastructure, making it easy to deploy and run.
Text-Based Flow Diagram:
[ User Browser (UI) ]
|
| 1. User inputs logs
v
[ App.tsx (State Management) ]
|
| 2. Triggers analysis -> calls services
v
[ vectorDBService.ts (RAG Retrieval) ] ----> [ localStorage (Knowledge Base) ]
^ ^
| 3. Searches for relevant past logs | 7. Saves new analysis
| and returns context |
v |
[ geminiService.ts (AI Logic) ] -----------------------+
|
| 4. Sends logs + RAG context to Gemini API
v
[ Google Gemini API (External) ]
|
| 5. Returns structured JSON analysis / chat stream
v
[ App.tsx (State Update) ]
|
| 6. Receives AI response
v
[ UI Components (Render) ] -> Displays results (charts, timeline, chat)
App.tsx: The central orchestrator. It manages all application state, including loading status, analysis results, and the chat session. It calls the various services to perform actions.components/: This directory contains all the React components responsible for rendering the UI. They are designed to be modular and reusable.services/: This directory contains the core business logic, decoupled from the UI.geminiService.ts: Handles all communication with the Gemini API.vectorDBService.ts: Manages thelocalStorageknowledge base and implements the TF-IDF search for the RAG system.solanaService.ts: Simulates the on-chain verification feature.
logX+ is designed for anyone who interacts with application or system logs.
- Scenario 1: Production Outage: A DevOps engineer is alerted to a critical server failure. Instead of manually searching through massive log files under pressure, they paste the relevant logs into logX+ and in seconds get a root cause analysis and a critical recommendation, pointing them to a database connection pool exhaustion issue.
- Scenario 2: Junior Developer Bug Fixing: A new developer encounters an unfamiliar
NullPointerException. They use logX+ to analyze the stack trace. The RAG system finds a similar issue from two weeks ago and informs the chat assistant. The assistant then provides highly specific advice: "This error often happens in theUserServicewhen a user profile is missing. Check if the user with ID123exists in the database, as that was the cause of a similar incident." - Target Audience: Software Developers, DevOps Engineers, Site Reliability Engineers (SREs), and Technical Support Staff.
While the current client-side architecture is perfect for a hackathon and personal use, the system is designed to be scalable.
Scalability:
- Backend Service: The
geminiServiceandvectorDBServicecan be migrated to a dedicated backend (e.g., a Python FastAPI or Node.js server). This would secure API keys, allow for more powerful RAG implementations, and enable multi-user knowledge bases. - Vector Database:
localStoragecan be replaced with a production-grade vector database like ChromaDB, Pinecone, or Weaviate. This would support millions of documents and enable true semantic search with powerful embedding models.
Future Improvements:
- Real-time Log Streaming: Integrate with logging platforms (like Datadog or Splunk) to analyze logs in real-time.
- Automated Ticketing: Add a feature to automatically create a Jira or GitHub issue based on the analysis results.
- RAG on Documentation: Allow users to upload their team's technical documentation or wikis to the knowledge base, so the AI's advice is grounded in the team's specific architecture and runbooks.
This project is an ideal fit for a hackathon for several key reasons:
- Solves a Real, Painful Problem: Every developer has struggled with log analysis. logX+ provides an elegant and immediate solution to this universal pain point.
- Sophisticated AI Implementation: It goes beyond a simple prompt-and-response. It uses advanced features like structured JSON output, streaming chat, and a clever client-side RAG implementation, showcasing a deep understanding of how to build practical AI tools.
- Innovative & Self-Contained: The use of
localStorageas a vector database for a client-side RAG system is an innovative approach that makes the project fully functional and impressive without requiring any backend infrastructure. It's a complete, end-to-end solution.
In short, logX+ is an intelligent assistant that turns the chaos of raw logs into clarity. It empowers developers to debug faster, understand complex systems more easily, and resolve issues with greater confidence. By combining a polished user interface with an advanced, RAG-powered AI engine, it demonstrates the future of developer tooling.