koriym / semantic-logger
Type-safe structured logging with schema validation and meaningful context
Requires
- php: ^8.1
Requires (Dev)
- bamarni/composer-bin-plugin: ^1.8
- justinrainbow/json-schema: ^6.4
- phpunit/phpunit: ^10.5
This package is auto-updated.
Last update: 2025-08-07 10:15:31 UTC
README
Type-safe structured logging with JSON schema validation for hierarchical application workflows.
AI-Native Analysis with MCP Server
Realizing Tim Berners-Lee's Semantic Web Vision - structured data that AI can understand and reason about autonomously.
# Install and run MCP server for Claude Code integration
composer require koriym/semantic-logger
php vendor/koriym/semantic-logger/bin/server.php /tmp
AI-Powered Performance Analysis
The included MCP Server provides two powerful tools for AI-native analysis:
getSemanticProfile
- Retrieve latest semantic performance profile with AI-optimized prompts
semanticAnalyze
- Execute PHP script with profiling + automatic AI analysis in one command
MCP Server Configuration
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json
):
{ "mcpServers": { "semantic-profiler": { "command": "php", "args": [ "vendor/koriym/semantic-logger/bin/server.php", "/tmp" ] } } }
See docs/mcp-setup.md for detailed configuration options.
Semantic Web Architecture
Everything is Linked for Machine Understanding:
- JSON Schema URLs - Every context includes
$schema
for semantic validation - JSON Pointer Links - Schema properties include
links
arrays pointing to specifications - RFC 8288 Relations - Standard
rel
attributes (describedby, related, canonical) for semantic connections - AI Interview Process - Regular AI feedback to minimize non-semantic noise
Example Schema with Semantic Links:
{ "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "method": { "type": "string", "enum": ["GET", "POST", "PUT", "DELETE"] } }, "links": [ { "anchor": "#/properties/method", "rel": "describedby", "href": "https://tools.ietf.org/html/rfc7231#section-4", "title": "HTTP Methods (RFC 7231)" } ] }
Semantic Web Mindset:
- Everything is machine-readable - No human-only documentation
- Links over comments - Semantic relationships through URIs, not prose
- AI as quality gatekeeper - Regular AI interviews to identify non-semantic patterns
- Schema-first design - Structure meaning before implementation
- Minimize semantic noise - Every field must have clear semantic purpose
This approach enables AI to autonomously understand system behavior, diagnose issues, and provide architectural insights beyond basic metrics.
DevLogger for Development
Development logging with AI-native analysis prompt generation:
use Koriym\SemanticLogger\DevLogger; use Koriym\SemanticLogger\SemanticLogger; // Initialize with log directory (defaults to system temp) $devLogger = new DevLogger('/path/to/logs'); // Output semantic logs with AI analysis prompts $semanticLogger = new SemanticLogger(); $devLogger->log($semanticLogger);
Creates two files:
semantic-dev-*.json
- Structured semantic log datasemantic-dev-*-prompt.md
- AI-optimized analysis prompt with embedded JSON
Perfect for development debugging and AI-assisted performance analysis.
Self-Proving Responses
Every response becomes self-proving by logging how it was generated. When your API returns "restaurant menu list", the semantic log proves why those specific items were returned through the complete chain of web API calls, database queries, and business logic.
Response (what): {"menu": ["pasta", "pizza", "salad"]}
Semantic Log (how/why): Complete proof of why these 3 items were returned
Provides equal context to both AI systems and human developers for comprehensive system understanding.
Beyond Traditional Logging: Semantic Structure
Traditional logging captures level and message for humans:
[INFO] User query executed: SELECT * FROM users WHERE id = 123
[DEBUG] Query took 12.5ms, returned 1 row
Semantic logging captures data structure AND meaning structure:
- Open: "what we plan to do" (intent)
- Event: "what happened during execution" (occurrences)
- Close: "what actually occurred" (result)
This structure enables understanding not just what happened, but why it happened and how it relates to the intended operation.
Best Practice: Use alongside traditional logging
- Traditional logs for quick debugging and stack traces
- Semantic logs for complex workflows and system analysis
Use Cases
- Development & Debugging - Complex workflow tracing with intent vs result analysis
- Compliance & Auditing - GDPR, SOX, HIPAA compliance with complete audit trails
- Security & Monitoring - Track data modifications and detect anomalous behavior
- Business Intelligence - Analyze behavior patterns and optimize processes
Features
- Type-safe context objects with const properties
- Hierarchical logging with open/event/close patterns
- JSON Schema validation for log entries
Structured, semantic, type-safe logging with web linking enables deep understanding for humans, AI, and data science.
Installation
composer require koriym/semantic-logger
Quick Start
1. Define Context Classes
Create type-safe context classes by extending AbstractContext
:
use Koriym\SemanticLogger\AbstractContext; final class ProcessContext extends AbstractContext { public const TYPE = 'process'; public const SCHEMA_URL = 'https://example.com/schemas/process.json'; public function __construct( public readonly string $name, ) {} } final class EventContext extends AbstractContext { public const TYPE = 'event'; public const SCHEMA_URL = 'https://example.com/schemas/event.json'; public function __construct( public readonly string $message, ) {} } final class ResultContext extends AbstractContext { public const TYPE = 'result'; public const SCHEMA_URL = 'https://example.com/schemas/result.json'; public function __construct( public readonly string $status, ) {} }
2. Log with Semantic Structure: Intent → Events → Result
use Koriym\SemanticLogger\SemanticLogger; $logger = new SemanticLogger(); // OPEN: Declare intent - what we plan to do $processId = $logger->open(new ProcessContext('data processing')); // EVENT: What happened during execution $logger->event(new EventContext('processing started')); // CLOSE: What actually occurred - the result $logger->close(new ResultContext('success'), $processId); // Optional: Add relations for debugging context $relations = [ ['rel' => 'related', 'href' => 'https://github.com/example/my-app', 'title' => 'Source Code Repository'], ['rel' => 'describedby', 'href' => 'https://example.com/db/schema/processes.sql', 'title' => 'Database Schema'] ]; // Get structured log with complete intent→result mapping $logJson = $logger->flush($relations); echo json_encode($logJson, JSON_PRETTY_PRINT);
3. Output Structure
The semantic structure captures the complete intent→result flow with hierarchical nesting:
{ "$schema": "https://koriym.github.io/Koriym.SemanticLogger/schemas/semantic-log.json", "open": { "type": "process", "schemaUrl": "https://example.com/schemas/process.json", "context": { "name": "data processing" }, "events": [ { "type": "event", "schemaUrl": "https://example.com/schemas/event.json", "context": { "message": "processing started" } } ], "close": { "type": "result", "schemaUrl": "https://example.com/schemas/result.json", "context": { "status": "success" } } }, "relations": [ { "rel": "related", "href": "https://github.com/example/my-app", "title": "Source Code Repository" }, { "rel": "describedby", "href": "https://example.com/db/schema/processes.sql", "title": "Database Schema" } ] }
Structure Meaning:
- open: Intent and planned operations with nested events and close results (hierarchical structure)
- events: Occurrences during execution (nested within their operation context)
- close: Actual results and outcomes (nested within the corresponding open operation)
- schemaUrl: JSON Schema URL for validation and documentation
- relations: Optional RFC 8288 compliant links (related resources, schemas, etc.)
Hierarchical Nesting Benefits:
- Request Tracing: Clear operation boundaries through nested structure in complex workflows
- Debugging: Trace the flow from intent (open) → events → result (close) within each operation context
- Monitoring: Track operation completion and identify unclosed operations
- Compliance: Maintain audit trails with clear operation boundaries
Documentation
Schema Portal - AI-native semantic schema portal with comprehensive documentation