Download the PHP package central-logs/laravel without Composer

Central Logs Laravel

A powerful and flexible Laravel package for sending logs to Central Logs system with support for synchronous, asynchronous, and batch processing modes. Achieve up to 251x faster logging performance with intelligent batch aggregation.

Features

• ✅ Multiple Log Levels - Support for all 8 Monolog levels (DEBUG → EMERGENCY)
• ✅ Three Operation Modes - Sync, Async (Queue), and Batch aggregation
• ✅ Blazing Fast - Batch mode is 251x faster than sync (0.68ms vs 170ms)
• ✅ Exception Handling - Automatic exception serialization with stack traces
• ✅ Context Enrichment - Automatic capture of user, request, session, and environment data
• ✅ Queue Integration - Seamless integration with Laravel Queue (Redis, Database, etc.)
• ✅ Auto-Flush - Multiple flush triggers (size, timeout, shutdown, memory)
• ✅ Retry Logic - Exponential backoff with configurable attempts (default: 3)
• ✅ Fallback Mechanism - Local logging when API is unavailable
• ✅ Zero Data Loss - Shutdown hooks ensure all logs are sent
• ✅ Production Ready - 100% test coverage, error handling, graceful degradation

Version Compatibility

Requirements

• PHP 8.0 or higher
• Laravel 9.x, 10.x, 11.x, or 12.x
• Guzzle HTTP Client 7.8+
• Central Logs instance (running at accessible URL)

Performance Benchmarks

Real-world performance testing with Central Logs API:

Batch mode processes logs 251x faster than sync mode!

Installation

Step 1: Install via Composer

Step 2: Publish Configuration

This will create a config/central-logs.php file in your Laravel application.

Important: The package will work in "null mode" (no logs sent) until you configure the API credentials in Step 3.

Step 3: Configure Environment

Add the following to your .env file:

Step 4: Add Middleware (Recommended for Batch Mode)

Add the flush middleware to app/Http/Kernel.php to ensure logs are sent at the end of each request:

Why? In batch mode, logs are collected and sent in batches. Without this middleware, logs may wait until batch size (default: 50) or timeout (default: 5s) is reached. The middleware ensures logs are flushed after each request.

Step 5: Update Logging Configuration

Add the Central Logs channel to your config/logging.php:

Step 6: Test Connection

Quick Start

Once configured, you can use Laravel's logging as usual:

Configuration

Logging Modes

Synchronous Mode

Logs are sent immediately (blocks the request):

Pros: Logs are sent immediately Cons: Adds latency to requests

Asynchronous Mode (Recommended)

Logs are queued and sent via Laravel Queue:

Pros: Non-blocking, fast Cons: Requires queue worker to be running

Batch Processing

Enable batch processing to reduce API calls:

How it works:

• Logs are collected in memory
• Flushed when batch size is reached OR timeout elapsed
• Automatically flushed on application shutdown

Configuration Reference

All available configuration options in config/central-logs.php:

Advanced Usage

Custom Metadata

Add custom metadata to all logs:

Using Specific Channel

Log only to Central Logs:

Conditional Logging

Log to Central Logs only in production:

Exception Handling

The package automatically extracts exception details:

Queue Configuration

For async mode, you need a queue worker running:

Using Redis (Recommended)

Using Database

Start Queue Worker

Supervisor Configuration

Create /etc/supervisor/conf.d/central-logs-worker.conf:

Troubleshooting

Connection Test Fails

Check:

1. Central Logs is running and accessible
2. API key is correct
3. Firewall/network settings allow connection
4. URL is correct (include http:// or https://)

Logs Not Appearing

In Async Mode:

• Check queue worker is running: ps aux | grep queue:work
• Check queue for failed jobs: php artisan queue:failed
• Check Laravel logs: tail -f storage/logs/laravel.log

In Batch Mode (Most Common Issue):

Problem: Logs not sent immediately, waiting until batch size or timeout reached

Solutions:

1. Add Flush Middleware (Recommended):

2. Lower Batch Settings for Development:

3. Disable Batching for Testing:

4. Manual Flush in Tinker:

Performance Issues

Sync mode is slow:

• Switch to async mode for better performance
• Enable batch mode to reduce API calls

Queue backing up:

• Increase number of queue workers
• Check Central Logs API response time
• Reduce batch timeout for faster processing

Development

Setup Development Environment

Run Tests

Code Quality

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Security

If you discover any security-related issues, please email [email protected] instead of using the issue tracker.

License

The MIT License (MIT). Please see LICENSE for more information.

Credits

• Pande
• All Contributors

Support

• Documentation
• Issue Tracker
• Email