🛡️ Kayal | Distributed Logging & Monitoring System

Kayal is a high-performance, centralized logging management system designed for modern microservices architectures. Built with Java 25 and Spring Boot 4.0.3, it provides real-time ingestion, intelligent log deduplication, and a professional administrative dashboard.

---

🚀 Key Features

📊 Professional Dashboard

• Real-time Monitoring: Integrated sidebar with "Live Pulse" badges showing offline services via Spring Boot Actuator heartbeats.
• Smart Ingestion: Automatic log deduplication (Upsert logic) that increments occurrence counts instead of bloating the DB.
• High-Performance Search: Server-side filtering using JPA Specifications and Criteria API for millisecond response times.
• Advanced Pagination: Efficient data fetching with "Jump to Page" and column sorting.

🔐 Enterprise Security

• RBAC (Role-Based Access Control): Tiered access for ADMIN and USER roles via Spring Security 6.
• Secure Ingestion: Protects external log injection endpoints with a custom X-API-KEY filter.
• Invitation System: Secure, token-based user registration with 24-hour expiration links.
• Argon2 Hashing: Industry-standard password security using the password4j Argon2 implementation.

🛠️ Developer Tools

• Deep Log Inspection: Dedicated "Terminal-style" view for stack traces with In-Log Regex Search.
• Trend Analytics: Visualized log frequency over time using Chart.js with PNG export capability.
• Email Alerts: Asynchronous email notifications for "Critical" keywords with 15-minute throttling to prevent inbox flooding.

---

💻 Tech Stack

• Backend: Java 25 (EA), Spring Boot 4.0.3, Spring Data JPA, Spring Security 6.
• Frontend: Thymeleaf, Tailwind CSS (JIT), Alpine.js (Reactive UI).
• Database: PostgreSQL 16 (Alpine).
• DevOps: Docker, Multi-stage Dockerfile, Paketo Buildpacks (Cloud Native).

---

🛠️ Getting Started

1. Environment Setup

Create a gradle/libs.versions.toml to manage dependencies and an application.yml for your secrets.

2. Run with Docker Compose

# Build the image using Buildpacks
./gradlew bootBuildImage

# Start the full stack (App + Database)
docker-compose up -d

3. Accessing the System

• Dashboard: http://localhost:8080/logs/dashboard
• Injection API: POST http://localhost:8080/api/v1/logs (Requires **X-API-KEY**)

📡 API Ingestion Example (REST Client)

You can inject logs from any external service using the following format. Ensure the **X-API-KEY** header matches your server configuration.

### 📡 API Ingestion Example
POST http://localhost:8080/api/v1/logs
Content-Type: application/json
X-API-KEY: {{your_secret_key}}

{
    "serviceId": "a38ae689-edea-4235-955c-c0348303f04a",
    "subject": "Database Connection Failed",
    "description": "Connection timed out after 30 seconds at 2024-06-01T12:00:00Z.",
    "level": "ERROR",
    "params": [
        {"key": "db_host", "value": "db.production.internal"},
        {"key": "retry_count", "value": "3"}
    ]
}

🧹 Maintenance

Kayal includes a Scheduled Cleanup Task that automatically purges logs older than 30 days every midnight to ensure database health and storage efficiency.

📄 License

Copyright © 2026 JSL Group. All rights reserved.