Search by

hakam / ai-log-inspector-agent

RamyHakam

AI-powered log inspector agent for PHP

Package info

github.com/RamyHakam/ai-log-inspector-agent

pkg:composer/hakam/ai-log-inspector-agent

Statistics

Installs: 26

Dependents: 1

Suggesters: 0

Stars: 5

Open Issues: 0


README

Tests PHP Version Symfony AI MCP Status License ๐Ÿ‡ต๐Ÿ‡ธ Free Palestine

๐Ÿค–๐Ÿ’ฌ 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

๐ŸŒ Traditional Way

  • Open Kibana/ElasticSearch dashboards
  • Write complex Datadog queries
  • Manual grep through log files
  • Filter thousands of log entries
  • Correlate timestamps & request IDs by hand
  • Spend hours finding root causes

Result: Hours of manual work ๐Ÿ˜ฉ

โšก AI Agent Way

// Just ask naturally!
$agent->ask("Why did payments fail?");
$agent->ask("What caused the 3 PM outage?");
$agent->ask("Show me timeout patterns");
$agent->ask("How many users affected?");

Result: Instant intelligent answers ๐Ÿง 

๐Ÿ”Œ 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 in src/Mcp, src/Parser, bin/ and examples/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.php for 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 /health
  • POST /init (preload sample logs and cache vectors)
  • POST /upload (upload log file, index with LogFileIndexer)
  • GET /logs
  • GET /init-status
  • POST /chat
  • POST /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:

  1. 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
  2. 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"
  3. 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

  1. Fork the repository
  2. Create feature branch: git checkout -b feature/amazing-feature
  3. Commit changes: git commit -m 'Add amazing feature'
  4. Push to branch: git push origin feature/amazing-feature
  5. Open Pull Request

Made with โค๏ธ for developers who hate digging through logs!

Transform your debugging experience today ๐Ÿš€