hakam / ai-log-inspector-agent
AI-powered log inspector agent for PHP
Requires
- php: ^8.4
- psr/log: ^3.0
- symfony/ai-agent: ^0.3.0
- symfony/ai-anthropic-platform: ^0.3.0
- symfony/ai-cache-store: ^0.3.0
- symfony/ai-chat: ^0.3.0
- symfony/ai-ollama-platform: ^0.3.0
- symfony/ai-open-ai-platform: ^0.3.0
- symfony/ai-platform: ^0.3.0
- symfony/ai-store: ^0.3.0
- symfony/cache: ^8.0
Requires (Dev)
- dg/bypass-finals: ^1.9
- symfony/dotenv: ^8.0
- symfony/test-pack: ^1.2
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.1.0
- dev-hackathon/symfony-ai-mcp
- dev-feature/add-playground-example-and-docs
- dev-feature/add-embbeding-platform-feature
- dev-feature/add-retriver-and-update-docs-ad-cs-fix
- dev-feature/add-indexer-feature
- dev-feature/add-more-tests
- dev-feature/Add-gitattributes-to-ignore-docs-and-examples-in-composer-install
- dev-feature/Add-Chat-Component-and-session-persistent
- dev-feature/init-the-Documentation
- dev-feature/Add-Request-context-tool
- dev-feature/upgrate-to-symfony-ai-first-release
- dev-feat/comprehensive-default-system-prompt
This package is auto-updated.
Last update: 2026-11-12 13:57:30 UTC
README
๐ค๐ฌ Chat With Your Logs Using Smart AI ๐ฌ๐ค
Transform debugging from tedious to effortless! ๐ โ โก
Stop digging through dashboards and complex queries. Just ask your logs directly in plain English.
๐ Traditional vs โก AI-Powered
๐ MCP Server: ask your logs from Claude Code, Cursor, โฆ
Built for the Symfony AI & MCP Hackathon (Oct 26 โ Nov 22, 2026). New in this round: upgraded to Symfony AI 1.0 and added an MCP server and demo client built on the official PHP MCP SDK (
mcp/sdk). All of it lives insrc/Mcp,src/Parser,bin/andexamples/incident-demo.
Your coding agent already reads your code. Now it can read your production logs too: search them semantically, trace one request across services, and run a full root-cause investigation, all through MCP.
flowchart LR
C["MCP client<br/>Claude Code ยท Cursor ยท Inspector"] -- "STDIO ยท JSON-RPC" --> S["bin/log-inspector-mcp<br/>mcp/sdk Server"]
S --> T1["log_search"] & T2["request_context"] & T4["index_logs"]
S --> T3["ask_logs"] --> A["Symfony AI Agent<br/>(tool-calling loop)"]
A --> T1 & T2
T1 & T2 --> R["Retriever + vector store<br/>Symfony AI Store"]
T4 --> P["LogLineParser โ Indexer<br/>(embeddings)"] --> R
Loading
| MCP element | Name | What it does |
|---|---|---|
| tool | log_search |
Semantic search over indexed logs. Returns evidence plus an explanation |
| tool | request_context |
Every line for a request_id / trace_id / session_id, in order |
| tool | ask_logs |
Runs the server-side Symfony AI agent, which picks the tools and writes a root-cause report |
| tool | index_logs |
Index a log file or a directory of *.log files |
| resource | logs://index/stats |
Indexed sources and line counts |
| prompt | investigate_incident |
A step-by-step incident investigation playbook for the client model |
โฑ๏ธ From git clone to a running demo in 5 minutes
The demo is an MCP client (also mcp/sdk). It starts the MCP server, indexes a simulated outage
(examples/incident-demo/logs: a deploy shrinks the DB pool from 50 to 5, checkout
fails, and customers are charged without orders) and investigates it.
git clone https://github.com/RamyHakam/ai-log-inspector-agent && cd ai-log-inspector-agent echo "OPENAI_API_KEY=sk-..." > .env # Option A: Docker docker compose run --rm demo # Option B: local PHP 8.4 composer install && php bin/log-inspector-demo # Ask your own question php bin/log-inspector-demo "Were any customers charged without getting an order?"
No API key? Run fully local with Ollama. Fastest on a Mac is native Ollama, which uses the GPU:
ollama pull llama3.2 && ollama pull nomic-embed-text LOG_INSPECTOR_PROVIDER=ollama php bin/log-inspector-demo # or from Docker, using the Ollama on your machine: LOG_INSPECTOR_PROVIDER=ollama OLLAMA_HOST=http://host.docker.internal:11434 docker compose run --rm demo
Everything in Docker also works, but Docker on macOS has no GPU, so expect several minutes per answer:
docker compose --profile local up -d --wait ollama # first start pulls llama3.2 + nomic-embed-text (~2.3 GB) LOG_INSPECTOR_PROVIDER=ollama docker compose run --rm demo
Small local models give shorter, less precise answers than hosted ones. With 8 GB or more of memory, try
LOG_INSPECTOR_MODEL=llama3.1 (pull it first).
Use it from Claude Code / Cursor
The repository ships an .mcp.json. Open the folder in Claude Code and the log-inspector server is
available. To use it with your own logs from any project:
claude mcp add log-inspector \ -e OPENAI_API_KEY=sk-... \ -e LOG_INSPECTOR_PATHS=/path/to/your-app/var/log \ -- php /path/to/ai-log-inspector-agent/bin/log-inspector-mcp
Or with Docker, which needs no local PHP:
{
"mcpServers": {
"log-inspector": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "OPENAI_API_KEY", "-e", "LOG_INSPECTOR_PATHS=/logs",
"-v", "/path/to/your-app/var/log:/logs:ro", "ai-log-inspector"]
}
}
}
Then just ask: "Use log-inspector to find out why checkout failed this afternoon", or start from the
investigate_incident prompt.
Configuration (environment variables or .env)
| Variable | Default | |
|---|---|---|
LOG_INSPECTOR_PROVIDER |
openai |
openai, anthropic or ollama |
LOG_INSPECTOR_MODEL |
gpt-5.4-mini / claude-sonnet-5-5 / llama3.2 |
chat model for the agent |
LOG_INSPECTOR_EMBEDDING_PROVIDER |
same as provider (ollama for anthropic) |
openai or ollama |
LOG_INSPECTOR_EMBEDDING_MODEL |
text-embedding-3-small / nomic-embed-text |
|
LOG_INSPECTOR_PATHS |
comma-separated files or directories to index at startup | |
OPENAI_API_KEY, ANTHROPIC_API_KEY, OLLAMA_HOST |
provider credentials / endpoint | |
OLLAMA_TIMEOUT |
300 |
seconds allowed per Ollama call (CPU-only machines are slow) |
The parser understands Monolog / Symfony / Laravel lines ([ts] channel.LEVEL: message {json} [extra]),
[ts] LEVEL: message and PHP error_log output. It extracts request_id, trace_id, session_id and
span_id from the JSON context, so request_context can trace requests across services.
๐ Docs & Examples
Live docs: ramyhakam.github.io/ai-log-inspector-agent
๐ Playground To Validate with your own logs and AI platform.
Playground: ramyhakam.github.io/ai-log-inspector-agent
๐ฌ Real Examples - Ask Anything!
$agent = new LogInspectorAgent($platform, $model, $store); // ๐จ Checkout Issues $result = $agent->ask('Why did the last checkout request fail?'); // โ "Payment gateway timeout after 30 seconds. The last 3 checkout attempts // all failed with 'gateway_timeout' errors between 14:23-14:25." // ๐ Database Problems $result = $agent->ask('Show me all database errors from the last hour'); // โ "Found 12 database connection failures. Pattern shows connection pool // exhaustion starting at 15:30, affecting user authentication service." // ๐ Performance Issues $result = $agent->ask('What caused the sudden spike in API response times?'); // โ "Memory leak in Redis connection causing 2.5s delays. Started after // deployment at 13:45, affecting 847 requests per minute." // ๐ Security Monitoring $result = $agent->ask('Are there any suspicious login attempts?'); // โ "Detected brute force attack from IP 192.168.1.100. 156 failed login // attempts in 5 minutes targeting admin accounts." // ๐ Impact Assessment $result = $agent->ask('How many users were affected by the outage?'); // โ "Based on error logs, approximately 2,341 unique users experienced // service disruption between 14:15-14:32 during the database incident."
โ ๏ธ Note - Built on Symfony AI (experimental). The package itself is NOT production-ready; platform maturity depends on your provider and deployment setup.
โจ What Makes It Special
๐ Semantic Search - Understands context, not just keywords
๐ง AI Analysis - Explains what happened and why
โก Lightning Fast - Get answers in seconds, not hours
๐ ๏ธ Tool-Based - Extensible architecture with Symfony AI
๐ Vector Powered - Smart similarity matching
๐ Fallback Ready - Works even when AI is unavailable
๐ Multi-Platform - OpenAI, Anthropic, and Ollama support
๐งฉ Multi-Tool - log_search + request_context for request tracing
๐ File Upload Indexing - Upload logs and index via LogFileIndexer
๐ฌ Session Chat - Persisted chat history for multi-turn investigations
๐งช Production Demo - Check Playground Demo
๐ Quick Start
Requirements
- PHP 8.4+
- Composer 2+
Install
composer require hakam/ai-log-inspector-agent
Setup & Use
<?php require_once __DIR__ . '/vendor/autoload.php'; use Hakam\AiLogInspector\Agent\LogInspectorAgent; use Hakam\AiLogInspector\Enum\PlatformEnum; use Hakam\AiLogInspector\Platform\LogDocumentPlatformFactory; use Hakam\AiLogInspector\Retriever\LogRetriever; use Hakam\AiLogInspector\Store\VectorLogDocumentStore; use Hakam\AiLogInspector\Tool\LogSearchTool; use Hakam\AiLogInspector\Tool\RequestContextTool; use Symfony\AI\Store\InMemory\Store as InMemoryStore; // Brain platform (LLM) + Embedding platform $brainPlatform = LogDocumentPlatformFactory::createBrainPlatform( PlatformEnum::OPENAI, [ 'api_key' => $_ENV['OPENAI_API_KEY'], 'model' => 'gpt-4o-mini', 'model_capabilities' => ['text', 'tool_calling'], ] ); $embeddingPlatform = LogDocumentPlatformFactory::createEmbeddingPlatform( PlatformEnum::OPENAI, [ 'api_key' => $_ENV['OPENAI_API_KEY'], 'model' => 'text-embedding-3-small', ] ); // Vector store + retriever $store = new VectorLogDocumentStore(new InMemoryStore()); $retriever = new LogRetriever( embeddingPlatform: $embeddingPlatform->getPlatform(), model: 'text-embedding-3-small', logStore: $store ); // Tools + agent $logSearchTool = new LogSearchTool($store, $retriever, $brainPlatform); $requestContextTool = new RequestContextTool($store, $retriever, $brainPlatform); $agent = new LogInspectorAgent($brainPlatform, [$logSearchTool, $requestContextTool]); // Index a few logs (in-memory) use Hakam\AiLogInspector\Document\LogDocumentFactory; use Hakam\AiLogInspector\Indexer\LogDocumentIndexer; $indexer = new LogDocumentIndexer( embeddingPlatform: $embeddingPlatform->getPlatform(), model: 'text-embedding-3-small', logStore: $store ); $docs = [ LogDocumentFactory::createFromString('[2024-01-29 14:23:45] ERROR: Payment gateway timeout'), LogDocumentFactory::createFromString('[2024-01-29 14:23:46] ERROR: Stripe API returned 504'), ]; $indexer->indexLogDocuments($docs); // Ask questions! $result = $agent->ask('Why did the checkout fail?'); echo $result->getContent();
Advanced Questions
// Root cause analysis $agent->ask('What caused the 500 errors in payment service?'); // Timeline investigation $agent->ask('What happened before the database failure?'); // Pattern discovery $agent->ask('Are there recurring memory leak patterns?'); // Security investigation $agent->ask('Suspicious auth patterns from IP 192.168.1.100?');
Response Structure
// Tool responses are structured (LogSearchTool / RequestContextTool / Playground API) [ 'success' => true, // Found relevant logs? 'reason' => 'Payment gateway timeout caused...', // AI explanation 'evidence_logs' => [ // Supporting evidence [ 'id' => 'log_001', 'content' => '[2024-01-15] ERROR: ...', 'timestamp' => '2024-01-15T14:23:45Z', 'level' => 'error', 'source' => 'payment-service', 'tags' => ['payment', 'timeout'] ] ] ]
LogInspectorAgent::ask() returns a ResultInterface (use getContent() for the AI response). The structured array above is the tool-level output used internally and by the playground API.
โ๏ธ Configuration
AI Platform Options
use Hakam\AiLogInspector\Enum\PlatformEnum; use Hakam\AiLogInspector\Platform\LogDocumentPlatformFactory; // OpenAI (brain + embeddings) $brainPlatform = LogDocumentPlatformFactory::createBrainPlatform( PlatformEnum::OPENAI, [ 'api_key' => $_ENV['OPENAI_API_KEY'], 'model' => 'gpt-4o-mini', 'model_capabilities' => ['text', 'tool_calling'], ] ); $embeddingPlatform = LogDocumentPlatformFactory::createEmbeddingPlatform( PlatformEnum::OPENAI, [ 'api_key' => $_ENV['OPENAI_API_KEY'], 'model' => 'text-embedding-3-small', ] ); // Anthropic (brain only, embeddings via OpenAI or local) $brainPlatform = LogDocumentPlatformFactory::createBrainPlatform( PlatformEnum::ANTHROPIC, [ 'api_key' => $_ENV['ANTHROPIC_API_KEY'], 'model' => 'claude-3-5-sonnet-20241022', 'model_capabilities' => ['text', 'tool_calling'], ] ); // Ollama (local brain + local embeddings) $brainPlatform = LogDocumentPlatformFactory::createBrainPlatform( PlatformEnum::OLLAMA, [ 'host' => 'http://localhost:11434', 'model' => 'llama3.2:1b', 'model_capabilities' => ['text', 'tool_calling'], ] ); $embeddingPlatform = LogDocumentPlatformFactory::createEmbeddingPlatform( PlatformEnum::OLLAMA, [ 'host' => 'http://localhost:11434', 'model' => 'nomic-embed-text', ] );
Vector Store Options
// Memory (testing) use Symfony\AI\Store\InMemory\Store as InMemoryStore; $store = new InMemoryStore(); // Production stores use Symfony\AI\Store\Bridge\Chroma\ChromaStore; use Symfony\AI\Store\Bridge\Pinecone\PineconeStore; $store = new ChromaStore($config); $store = new PineconeStore($config);
Custom System Prompts
$customPrompt = 'You are a security log analyzer. Focus on threats and incidents.'; $agent = new LogInspectorAgent($platform, [$logSearchTool, $requestContextTool], $customPrompt);
๐งฐ Tools & Capabilities
LogSearchTool (log_search)
- Semantic or keyword search over indexed logs
- Returns structured results with evidence logs and AI analysis
RequestContextTool (request_context)
- Trace a request, session, or trace ID across distributed logs
- Returns chronological log context for end-to-end debugging
Multi-tool agent example
- See
examples/multi-tool-agent-example.phpfor intelligent tool selection
๐ฌ Conversational Debugging
use Hakam\AiLogInspector\Chat\LogInspectorChatFactory; $chat = LogInspectorChatFactory::createSession( sessionId: 'incident-2026-02-06', platform: $platform, searchTool: $logSearchTool, contextTool: $requestContextTool, storagePath: sys_get_temp_dir() . '/log-inspector-sessions' ); $chat->startInvestigation('Payment outage - Feb 6, 2026'); $chat->ask('What payment errors occurred?'); $chat->followUp('Were there any database issues around that time?'); $summary = $chat->summarize(); echo $summary->asText();
๐งช Playground API
Run the multi-platform playground API:
php -S localhost:8080 examples/playground-api.php
Key endpoints:
GET /healthPOST /init(preload sample logs and cache vectors)POST /upload(upload log file, index withLogFileIndexer)GET /logsGET /init-statusPOST /chatPOST /reset
Features:
- Separate brain and embedding models per request
- OpenAI, Anthropic, or Ollama per request
- Session-based chat history
- Cached vector store per session
Environment variables:
OLLAMA_URL(default:http://localhost:11434)OLLAMA_MODEL(default:llama3.1:8b)CHROMA_URL(default:http://localhost:8000)CHROMA_COLLECTION(default:log-inspector)REDIS_URL(default:redis://localhost:6379)ALLOWED_ORIGINS(default:*)
๐ Local Docs
The documentation site content is in website/docs.
Live docs: ramyhakam.github.io/ai-log-inspector-agent
๐งช Testing & Validation - REAL WORKING PACKAGE
๐ฏ PROOF IT WORKS: Comprehensive end-to-end tests with real Ollama integration.
โ Full Functional Test Suite
13/13 tests PASSING with real Ollama (llama3.2:1b):
- ๐ณ Payment system analysis - Real e-commerce error investigation
- ๐ก๏ธ Security incident detection - Brute force & auth failure analysis
- ๐พ Database performance issues - Connection timeouts & query problems
- ๐ Application error analysis - Exception handling & memory issues
- โก Performance monitoring - API response time analysis
- ๐ 50+ realistic PHP logs from actual applications
๐โโ๏ธ Run Tests Yourself
# Setup Ollama curl -fsSL https://ollama.ai/install.sh | sh ollama pull llama3.2:1b # Run full test suite OLLAMA_MODEL=llama3.2:1b vendor/bin/phpunit test/Functional/
Results: 104 successful assertions, 2-10s response times, multi-platform support proven.
๐ Extend Testing
Want to test with YOUR logs? Add more realistic log examples:
-
Expand
test/fixtures/logs/with logs from:- โ Laravel applications - Real Laravel/Eloquent errors (included)
- โ Kubernetes pods - OOMKilled, CrashLoopBackOff, resource issues (included)
- โ Microservices - Circuit breakers, service mesh, distributed tracing (included)
- Symfony applications
- API gateways
- Docker containers
-
Test real scenarios:
- "What caused the 3 AM outage?"
- "Show me memory leaks in user service"
- "Find all failed credit card transactions"
- "Analyze API rate limiting errors"
-
Validate with your AI platform:
- OpenAI (full semantic search)
- Anthropic (full semantic search)
- Ollama (intelligent keyword fallback)
This package works with REAL data and REAL AI models - test it yourself!
๐ค Contributing
- Fork the repository
- Create feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open Pull Request
Made with โค๏ธ for developers who hate digging through logs!
Transform your debugging experience today ๐