itrunsde / laravel-logscale

v1.0.0 2026-08-06 09:55 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/log: ^11.0|^12.0|^13.0
• illuminate/queue: ^11.0|^12.0|^13.0
• illuminate/redis: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• monolog/monolog: ^3.0

Requires (Dev)

• mockery/mockery: ^1.6
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-laravel: ^4.0

MIT

• Sebastian Selig

Published on Packagist.org on 2026-08-06 13:52 UTC

README

Laravel logging channel that ships structured application logs to Falcon LogScale via the HTTP ingest API.

This package complements the Falcon LogScale Collector. Use the collector for host- and file-based ingestion. Use this package when you need Laravel-native logging on shared hosting, PaaS, or anywhere a host agent is not available.

Requirements

• PHP ^8.2
• Laravel 11, 12, or 13
• Redis (required only when LOGSCALE_DELIVERY=queue)

Installation

composer require itrunsde/laravel-logscale

The service provider is auto-discovered. Publish the config when you want to customize redaction lists or inspect defaults:

php artisan vendor:publish --tag=logscale-config

Configuration

Set credentials and tags in .env:

Env / config	Purpose	Default
LOGSCALE_URL	LogScale base URL (no ingest path)	—
LOGSCALE_TOKEN	Ingest token	—
LOGSCALE_SERVICE	Tag #service	APP_NAME
LOGSCALE_ENV	Tag #env	APP_ENV
LOGSCALE_DELIVERY	sync or queue	sync
LOGSCALE_RELEASE	Release attribute on events	APP_VERSION
LOGSCALE_COMMIT	Commit attribute on events	—
LOGSCALE_FALLBACK_CHANNEL	Laravel channel used when ingest fails	single
LOGSCALE_BUFFER_SIZE	Queue mode: flush when buffer reaches this size	50
LOGSCALE_BUFFER_AGE	Queue mode: flush when oldest event reaches this age (seconds)	5
LOGSCALE_TRACE_FRAMES	Max exception stack frames	20
LOGSCALE_TIMEOUT	HTTP timeout (seconds)	5

Add a channel in config/logging.php:

'logscale' => [
    'driver' => 'logscale',
    'level' => env('LOG_LEVEL', 'debug'),
],

Use it like any other channel:

Log::channel('logscale')->info('Order placed', ['order_id' => 123]);

Sensitive keys in log context are redacted recursively by default (password, token, authorization, and others). Override deny/allow lists in config/logscale.php after publishing.

Step-by-step guide and LogScale queries

For a complete walkthrough—including configuration, redaction and fallback validation, Redis queue delivery, and troubleshooting—see the published MyLogScale guide:

• Send Structured Laravel Logs to Falcon LogScale with laravel-logscale

The guide is the living companion to this README and will link to additional LogScale queries and related examples as they are published.

Delivery modes

Sync (LOGSCALE_DELIVERY=sync)

Each log record is sent immediately in one HTTP request. Failures are swallowed: the event is written to the fallback channel and the application continues.

No Redis, queue worker, or scheduler setup is required.

Queue (LOGSCALE_DELIVERY=queue)

Events are buffered in Redis and flushed in batches. Requires:

1. Redis — configured as Laravel's default Redis connection. The package fails fast if Redis is unavailable.
2. Queue worker — FlushBufferJob must be processed (e.g. php artisan queue:work).
3. Scheduler — Laravel's scheduler must run every minute (cron: * * * * * php artisan schedule:run). The provider registers FlushBufferJob every five seconds with withoutOverlapping() to flush by age.

Buffering uses Redis list logscale:buffer and companion ZSET logscale:buffer:times. A flush runs when the buffer reaches LOGSCALE_BUFFER_SIZE or when the oldest event exceeds LOGSCALE_BUFFER_AGE. Failed flush jobs retry three times with backoff; after the final failure, events are logged to the fallback channel and dropped.

Manual validation

Run these steps against a real LogScale repository (not in CI):

1. Install the package in a Laravel 11, 12, or 13 app and set LOGSCALE_URL, LOGSCALE_TOKEN, and the logscale logging channel.
2. Emit a test log: Log::channel('logscale')->info('laravel-logscale smoke test', ['check' => 'ok']);
3. In LogScale, confirm the event appears with #service and #env tags, ISO timestamp, and expected attributes.
4. Log with a sensitive key (e.g. password) and confirm it is redacted to [REDACTED].
5. Trigger an exception and confirm exception attributes (class, message, truncated trace) are present.
6. With LOGSCALE_DELIVERY=queue, confirm batched delivery after buffer size or age threshold; verify Redis keys drain after flush.
7. Simulate ingest failure (invalid token or URL) and confirm the fallback channel receives the event without breaking the request.

License

MIT