AI Log Inspector Agent Documentation
Welcome to the complete documentation for the AI Log Inspector Agent - a production-ready PHP package for intelligent log analysis powered by AI.
๐ New: MCP Serverโ
Use the log inspector from Claude Code, Cursor or any MCP client. The server is built on the official PHP MCP SDK
and Symfony AI 1.0, and exposes log_search, request_context, ask_logs and index_logs.
echo "OPENAI_API_KEY=sk-..." > .env && docker compose run --rm demo
- MCP Server - Tools, resource, prompt and how they work
- Connect a Client - Claude Code, Cursor, Claude Desktop, Docker
- Incident Demo - Investigate a simulated outage in one command
- Upgrading to Symfony AI 1.0 - What changed
๐ Quick Linksโ
- Overview - What is this package and why use it?
- Installation - Get started in minutes
- Quick Start - Your first log inspector in 5 minutes
- Architecture - How it works under the hood
๐ Documentation Sectionsโ
Introductionโ
Get familiar with the package and its capabilities.
- Overview - Package introduction and key benefits
- Why AI Log Inspector? - See what makes it unique
- Real-World Use Cases - Production examples
Getting Startedโ
Install and configure your first log inspector.
- Installation - System requirements and setup
- Quick Start - 5-minute tutorial
- Configuration - Advanced configuration options
Core Conceptsโ
Understand the architecture and design principles.
- Architecture - System design and components
- Vector Stores - Storage backends
- Semantic Search - How vector search works
- Platform Abstraction - Multi-platform support
Toolsโ
Deep dive into available tools and how to use them.
- LogSearchTool - Semantic log search
- RequestContextTool - Request tracing
- Custom Tools - Build your own tools
Usage & Featuresโ
Learn how to use the package effectively.
- Basic Usage - Common patterns and examples
- Chat Interface - Conversational debugging
- Log Indexing - Load and process logs
- Multi-Platform - Using different AI providers
Advanced Topicsโ
Production deployment and optimization.
- Best Practices - Production patterns
- Performance Tuning - Optimize for scale
- Security - Secure deployment
- Custom Tools - Extensibility guide
API Referenceโ
Complete API documentation.
- LogInspectorAgent - Main agent class
- LogInspectorChat - Chat interface
- Tools - Tool interfaces
- Factories - Factory classes
Examplesโ
Real-world code examples and patterns.
- Basic Usage - Simple examples
- Production Setup - Full production example
- Laravel Integration - Laravel-specific examples
- Symfony Integration - Symfony-specific examples
๐ฏ Common Tasksโ
How do I...โ
...install the package?
โ See Installation
...create my first agent?
โ Follow the Quick Start guide
...search logs semantically?
โ Use LogSearchTool
...trace a request across services?
โ Use RequestContextTool
...use conversations instead of single questions?
โ Check out the Chat Interface
...switch AI providers (OpenAI/Anthropic/Ollama)?
โ Read Multi-Platform Usage
...deploy to production?
โ Follow Best Practices
...create custom tools?
โ See Custom Tools Guide
๐ก Key Featuresโ
๐ง Intelligent Analysisโ
Ask natural language questions and get AI-powered answers with evidence citations.
$agent->ask('Why did the payment fail for order #12345?');
// โ AI explains root cause with supporting log entries
๐ฌ Conversational Debuggingโ
Multi-turn conversations that remember context.
$chat->ask('What errors occurred?');
$chat->followUp('Were there database issues?');
$chat->ask('What was the root cause?');
๐ Semantic Searchโ
Understands meaning, not just keywords.
// Finds "transaction timeout", "payment gateway error", etc.
$agent->ask('payment problems');
๐ ๏ธ Extensible Toolsโ
Build your own tools for custom analysis.
$agent = new LogInspectorAgent($platform, [
$logSearchTool,
$requestContextTool,
$customSecurityTool // Your custom tool
]);
๐ฏ Multi-Platformโ
Works with OpenAI, Anthropic, Ollama, and custom platforms.
// Switch providers without changing your code
$agent = LogInspectorAgentFactory::createWithOpenAI($apiKey);
// OR
$agent = LogInspectorAgentFactory::createWithAnthropic($apiKey);
// OR
$agent = LogInspectorAgentFactory::createWithOllama('llama3.2:1b');
๐งช Production Readyโ
โ
13/13 tests passing with real AI integrations
โ
104+ assertions across unit, functional, and integration tests
โ
Real log examples from Laravel, Kubernetes, microservices
โ
PHP 8.4+ compatible with modern type system
โ
Symfony AI powered using battle-tested components
๐ Learn by Exampleโ
Simple Queryโ
require 'vendor/autoload.php';
$agent = LogInspectorAgentFactory::createWithOpenAI($_ENV['OPENAI_API_KEY']);
// Load logs
foreach ($logs as $log) {
$agent->indexLog(TextDocumentFactory::createFromString($log));
}
// Ask questions
$result = $agent->ask('Show me all payment errors');
echo $result->getContent();
Conversational Investigationโ
$chat = LogInspectorChatFactory::createWithOpenAI($_ENV['OPENAI_API_KEY']);
$chat->startInvestigation('Payment incident - Jan 29');
echo $chat->ask('What payment errors occurred?')->asText();
echo $chat->followUp('What was the root cause?')->asText();
echo $chat->summarize()->asText();
Request Tracingโ
$agent = new LogInspectorAgent($platform, [
new LogSearchTool($store, $retriever, $platform),
new RequestContextTool($store, $retriever, $platform)
]);
// Trace complete request lifecycle
$result = $agent->ask('Debug request req_12345');
// โ Shows all logs across all services for that request
๐ค Contributingโ
This is an open-source project. Contributions are welcome!
- Report bugs: GitHub Issues
- Suggest features: GitHub Discussions
- Submit PRs: Fork and create pull requests
๐ Licenseโ
MIT License - see LICENSE file for details.
๐ Need Help?โ
- Documentation: You're reading it!
- Examples: Check the examples/ section
- Issues: GitHub Issues
- Email: ramy.hakam@gmail.com
Ready to get started? โ Begin with the Quick Start Guide
Want to understand the architecture? โ Read the Architecture Overview
Looking for examples? โ Browse the Examples section