PHPackages                             central-logs/laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. central-logs/laravel

ActiveLibrary[Logging & Monitoring](/categories/logging)

central-logs/laravel
====================

Laravel package for sending logs to Central Logs system with sync, async, and batch processing modes. Achieve 251x faster logging performance.

v1.3.0(5mo ago)17.6k↓81.8%MITPHPPHP ^8.0CI passing

Since Dec 19Pushed 5mo agoCompare

[ Source](https://github.com/pandeptwidyaop/central-logs-laravel)[ Packagist](https://packagist.org/packages/central-logs/laravel)[ Docs](https://github.com/pandeptwidyaop/central-logs-laravel)[ RSS](/packages/central-logs-laravel/feed)WikiDiscussions main Synced 4d ago

READMEChangelog (8)Dependencies (11)Versions (10)Used By (0)

Central Logs Laravel
====================

[](#central-logs-laravel)

[![Latest Version on Packagist](https://camo.githubusercontent.com/99c41f7497bfd26325c14c74d7cf919325cef6c0c02a328fd5b4ef5793c03dda/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f63656e7472616c2d6c6f67732f6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/central-logs/laravel)[![Tests](https://camo.githubusercontent.com/49863894734d6b3ac6d016a365f917b4b8f2e77ddd1e757bbc1fcd80f074765c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70616e6465707477696479616f702f63656e7472616c2d6c6f67732d6c61726176656c2f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/pandeptwidyaop/central-logs-laravel/actions/workflows/tests.yml)[![PHPStan](https://camo.githubusercontent.com/1c861cd21fc2a647b43417cadfb45150db7b638c6a7956297de89108a6a5524d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f70616e6465707477696479616f702f63656e7472616c2d6c6f67732d6c61726176656c2f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7068707374616e267374796c653d666c61742d737175617265)](https://github.com/pandeptwidyaop/central-logs-laravel/actions/workflows/tests.yml)[![Total Downloads](https://camo.githubusercontent.com/a8769a08548dfedaaa32ddbe892b1ba4c3214f4ab719abb6e4b42abe546b5439/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f63656e7472616c2d6c6f67732f6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/central-logs/laravel)[![License](https://camo.githubusercontent.com/a6e5f67009158985008cbe7f23de855738db8c6c52f24b03ee648dbab9d5f33c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f63656e7472616c2d6c6f67732f6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](LICENSE)

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
--------

[](#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
---------------------

[](#version-compatibility)

Package VersionLaravelPHPMonolog1.3+9.x, 10.x, 11.x, 12.x^8.0^2.0|^3.01.0-1.210.x, 11.x, 12.x^8.1^3.0Requirements
------------

[](#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
----------------------

[](#performance-benchmarks)

Real-world performance testing with Central Logs API:

ModeSpeedBlockingQueuedSpeedupBest For**SYNC**170.83msYesNo1xCritical logs**ASYNC**57.71msNoYes3xHigh-throughput**BATCH**0.68msNoOn flush**251x**Optimal performance**Batch mode processes logs 251x faster than sync mode!**

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require central-logs/laravel
```

### Step 2: Publish Configuration

[](#step-2-publish-configuration)

```
php artisan vendor:publish --tag=central-logs-config
```

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

[](#step-3-configure-environment)

Add the following to your `.env` file:

```
CENTRAL_LOGS_URL=https://your-central-logs-domain.com
CENTRAL_LOGS_API_KEY=your_api_key_here
CENTRAL_LOGS_MODE=async
CENTRAL_LOGS_BATCH_ENABLED=true
```

### Step 4: Add Middleware (Recommended for Batch Mode)

[](#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:

```
protected $middleware = [
    // ... other middleware
    \CentralLogs\Http\Middleware\FlushCentralLogsMiddleware::class,
];
```

**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

[](#step-5-update-logging-configuration)

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

```
'channels' => [
    // Option 1: Use Central Logs directly
    'central-logs' => [
        'driver' => 'monolog',
        'handler' => CentralLogs\Handler\CentralLogsHandler::class,
        'level' => env('LOG_LEVEL', 'debug'),
    ],

    // Option 2: Add to stack (recommended)
    'stack' => [
        'driver' => 'stack',
        'channels' => ['daily', 'central-logs'],
        'ignore_exceptions' => false,
    ],
],
```

### Step 6: Test Connection

[](#step-6-test-connection)

```
php artisan central-logs:test
```

Quick Start
-----------

[](#quick-start)

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

```
use Illuminate\Support\Facades\Log;

// Simple logging
Log::info('User logged in');

// With context
Log::info('User logged in', [
    'user_id' => $user->id,
    'ip' => request()->ip(),
]);

// Error logging with exception
try {
    // ... your code
} catch (Exception $e) {
    Log::error('Payment processing failed', [
        'exception' => $e,
        'order_id' => $order->id,
    ]);
}

// Different log levels
Log::debug('Debugging information');
Log::info('Informational message');
Log::warning('Warning message');
Log::error('Error occurred');
Log::critical('Critical issue');
```

Configuration
-------------

[](#configuration)

### Logging Modes

[](#logging-modes)

#### Synchronous Mode

[](#synchronous-mode)

Logs are sent immediately (blocks the request):

```
CENTRAL_LOGS_MODE=sync
```

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

#### Asynchronous Mode (Recommended)

[](#asynchronous-mode-recommended)

Logs are queued and sent via Laravel Queue:

```
CENTRAL_LOGS_MODE=async
QUEUE_CONNECTION=redis  # or database
```

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

```
php artisan queue:work --queue=central-logs
```

### Batch Processing

[](#batch-processing)

Enable batch processing to reduce API calls:

```
CENTRAL_LOGS_BATCH_ENABLED=true
CENTRAL_LOGS_BATCH_SIZE=50      # Number of logs per batch
CENTRAL_LOGS_BATCH_TIMEOUT=5    # Seconds before auto-flush
```

**How it works:**

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

### Configuration Reference

[](#configuration-reference)

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

```
return [
    // API endpoint
    'api_url' => env('CENTRAL_LOGS_URL'),
    'api_key' => env('CENTRAL_LOGS_API_KEY'),

    // Mode: sync or async
    'mode' => env('CENTRAL_LOGS_MODE', 'async'),

    // Batch configuration
    'batch' => [
        'enabled' => env('CENTRAL_LOGS_BATCH_ENABLED', true),
        'size' => env('CENTRAL_LOGS_BATCH_SIZE', 50),
        'timeout' => env('CENTRAL_LOGS_BATCH_TIMEOUT', 5),
        'queue' => env('CENTRAL_LOGS_BATCH_QUEUE', 'central-logs'),
    ],

    // Source identifier
    'source' => env('CENTRAL_LOGS_SOURCE', env('APP_NAME', 'laravel')),

    // HTTP client settings
    'http' => [
        'timeout' => env('CENTRAL_LOGS_TIMEOUT', 5),
        'retry' => [
            'times' => env('CENTRAL_LOGS_RETRY_TIMES', 3),
            'delay' => env('CENTRAL_LOGS_RETRY_DELAY', 100),
        ],
        'verify_ssl' => env('CENTRAL_LOGS_VERIFY_SSL', true),
    ],

    // Fallback when Central Logs is unavailable
    'fallback' => [
        'enabled' => env('CENTRAL_LOGS_FALLBACK', true),
        'channel' => env('CENTRAL_LOGS_FALLBACK_CHANNEL', 'stack'),
    ],

    // Context enrichment
    'context' => [
        'include_user' => true,
        'include_request' => true,
        'include_session' => true,
        'include_environment' => true,
        'custom' => [
            // Add custom metadata here
        ],
    ],

    // Minimum log level
    'level' => env('CENTRAL_LOGS_LEVEL', 'DEBUG'),

    // Queue configuration
    'queue' => [
        'connection' => env('CENTRAL_LOGS_QUEUE_CONNECTION'),
        'name' => env('CENTRAL_LOGS_QUEUE_NAME', 'central-logs'),
    ],

    // Debug mode
    'debug' => env('CENTRAL_LOGS_DEBUG', false),
];
```

Advanced Usage
--------------

[](#advanced-usage)

### Custom Metadata

[](#custom-metadata)

Add custom metadata to all logs:

```
// config/central-logs.php
'context' => [
    'custom' => [
        'app_version' => '1.2.3',
        'datacenter' => 'us-east-1',
        'environment_type' => 'staging',
    ],
],
```

### Using Specific Channel

[](#using-specific-channel)

Log only to Central Logs:

```
Log::channel('central-logs')->info('This goes only to Central Logs');
```

### Conditional Logging

[](#conditional-logging)

Log to Central Logs only in production:

```
if (app()->environment('production')) {
    Log::channel('central-logs')->info('Production log');
} else {
    Log::info('Development log');
}
```

### Exception Handling

[](#exception-handling)

The package automatically extracts exception details:

```
try {
    throw new \RuntimeException('Something went wrong');
} catch (\Exception $e) {
    Log::error('An error occurred', [
        'exception' => $e,  // Automatically formatted
        'user_id' => auth()->id(),
    ]);
}
```

Queue Configuration
-------------------

[](#queue-configuration)

For async mode, you need a queue worker running:

### Using Redis (Recommended)

[](#using-redis-recommended)

```
# .env
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
```

### Using Database

[](#using-database)

```
# .env
QUEUE_CONNECTION=database

# Create queue tables
php artisan queue:table
php artisan migrate
```

### Start Queue Worker

[](#start-queue-worker)

```
# Production (with Supervisor)
php artisan queue:work --queue=central-logs --tries=3 --timeout=30

# Development
php artisan queue:listen --queue=central-logs
```

### Supervisor Configuration

[](#supervisor-configuration)

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

```
[program:central-logs-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/your/app/artisan queue:work --queue=central-logs --tries=3
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/path/to/your/app/storage/logs/worker.log
stopwaitsecs=3600
```

Troubleshooting
---------------

[](#troubleshooting)

### Connection Test Fails

[](#connection-test-fails)

```
php artisan central-logs:test
```

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

[](#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):**

    ```
    // app/Http/Kernel.php
    protected $middleware = [
        \CentralLogs\Http\Middleware\FlushCentralLogsMiddleware::class,
    ];
    ```
2. **Lower Batch Settings for Development:**

    ```
    # .env
    CENTRAL_LOGS_BATCH_SIZE=10    # Lower from default 50
    CENTRAL_LOGS_BATCH_TIMEOUT=2  # Lower from default 5
    ```
3. **Disable Batching for Testing:**

    ```
    # .env
    CENTRAL_LOGS_BATCH_ENABLED=false
    ```
4. **Manual Flush in Tinker:**

    ```
    php artisan tinker
    app(\CentralLogs\Support\BatchAggregator::class)->flush();
    ```

### Performance Issues

[](#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
-----------

[](#development)

### Setup Development Environment

[](#setup-development-environment)

```
# Clone repository
git clone https://github.com/yourusername/central-logs-laravel.git
cd central-logs-laravel

# Start Docker environment
docker-compose up -d

# Install dependencies
docker-compose exec php composer install

# Set up test app
docker-compose exec php sh
cd /var/www/test-app
./setup.sh
```

### Run Tests

[](#run-tests)

```
# All tests
composer test

# Unit tests only
vendor/bin/phpunit --testsuite Unit

# With coverage
composer test-coverage
```

### Code Quality

[](#code-quality)

```
# PHPStan
composer phpstan

# Code formatting
composer format
```

Contributing
------------

[](#contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

Security
--------

[](#security)

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

License
-------

[](#license)

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

Credits
-------

[](#credits)

- [Pande](https://github.com/pande)
- [All Contributors](../../contributors)

Support
-------

[](#support)

- [Documentation](https://github.com/pandeptwidyaop/central-logs-laravel)
- [Issue Tracker](https://github.com/pandeptwidyaop/central-logs-laravel/issues)
- [Email](mailto:dev@pande.id)

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance70

Regular maintenance activity

Popularity25

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 80% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

8

Last Release

169d ago

PHP version history (3 changes)v1.0.0PHP ^8.2

v1.2.0PHP ^8.0

v1.2.1PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/0ebb67c782922dbea9ff7cde85f5b9c6486bedd5fbd326be1d06ac2894cdb1dc?d=identicon)[pandeptwidyaop](/maintainers/pandeptwidyaop)

---

Top Contributors

[![pandeptwidyaop](https://avatars.githubusercontent.com/u/16359161?v=4)](https://github.com/pandeptwidyaop "pandeptwidyaop (32 commits)")[![semantic-release-bot](https://avatars.githubusercontent.com/u/32174276?v=4)](https://github.com/semantic-release-bot "semantic-release-bot (8 commits)")

---

Tags

laravelloggingqueuemonologobservabilitylog-aggregationcentral-logsbatch-loggingasync-logging

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/central-logs-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/central-logs-laravel/health.svg)](https://phpackages.com/packages/central-logs-laravel)
```

###  Alternatives

[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k95.4M307](/packages/laravel-horizon)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[spatie/laravel-health

Monitor the health of a Laravel application

87512.0M167](/packages/spatie-laravel-health)[laravel/boost

Laravel Boost accelerates AI-assisted development by providing the essential context and structure that AI needs to generate high-quality, Laravel-specific code.

3.5k21.5M603](/packages/laravel-boost)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M203](/packages/laravel-ai)[flarum/core

Delightfully simple forum software.

201.4M2.3k](/packages/flarum-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)