Send Structured Laravel Logs to Falcon LogScale with laravel-logscale

Use itrunsde/laravel-logscale when you need Laravel-native, structured application logging in Falcon LogScale but cannot or do not want to run a host collector. It sends events through the HTTP ingest API. For host and file-based ingestion, use the Falcon LogScale Collector instead.

What you need

• PHP 8.2 or later
• Laravel 11, 12, or 13
• A Falcon LogScale base URL and ingest token
• Redis only when using queued delivery

1. Install the package

composer require itrunsde/laravel-logscale

Laravel auto-discovers the service provider. Publish the configuration if you want to inspect defaults or customize the sensitive-field allow/deny lists:

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

2. Configure credentials and event tags

Add the required endpoint and token to your .env. LOGSCALE_URL is the base URL; do not append an ingest path. Keep LOGSCALE_TOKEN out of source control.

LOGSCALE_URL=https://your-logscale.example
LOGSCALE_TOKEN=replace-with-your-ingest-token
LOGSCALE_SERVICE=my-laravel-app
LOGSCALE_ENV=production

# Start with synchronous delivery.
LOGSCALE_DELIVERY=sync

# Optional release metadata
LOGSCALE_RELEASE=2026.08.06
LOGSCALE_COMMIT=your-commit-sha

The package defaults LOGSCALE_SERVICE to APP_NAME, LOGSCALE_ENV to APP_ENV, and LOGSCALE_RELEASE to APP_VERSION. It also supports LOGSCALE_FALLBACK_CHANNEL (default: single), LOGSCALE_TIMEOUT (default: five seconds), and LOGSCALE_TRACE_FRAMES (default: 20).

3. Register the LogScale channel

Add a channel to config/logging.php:

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

Then log to it as you would to any Laravel channel:

use Illuminate\Support\Facades\Log;

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

Events include the configured #service and #env tags. Exceptions include class, message, and a truncated trace.

4. Confirm redaction and fallback behavior

Sensitive context keys are recursively redacted by default, including password, token, and authorization; values are replaced with [REDACTED]. Adjust the allow/deny lists in config/logscale.php only after publishing the package configuration.

With the default sync delivery mode, every record is sent immediately. If ingestion fails, the package writes the event to the configured fallback channel and allows the request to continue. No Redis, queue worker, or scheduler is required in this mode.

5. Optionally batch events through Redis

For buffered delivery, set:

LOGSCALE_DELIVERY=queue
LOGSCALE_BUFFER_SIZE=50
LOGSCALE_BUFFER_AGE=5

Queue mode requires all of the following:

1. Redis configured as Laravel's default Redis connection. The package fails fast when Redis is unavailable.

2. A queue worker that processes FlushBufferJob, for example:

   php artisan queue:work
   

3. Laravel's scheduler running every minute:

   * * * * * php /path/to/artisan schedule:run
   

The package buffers events in Redis and flushes them when the buffer reaches LOGSCALE_BUFFER_SIZE or the oldest event reaches LOGSCALE_BUFFER_AGE. Failed flush jobs retry three times with backoff. After the final failure, the events are written to the fallback channel and dropped.

6. Validate the integration

Run this against a real LogScale repository rather than only in CI:

1. Emit a smoke-test event:

   Log::channel('logscale')->info('laravel-logscale smoke test', ['check' => 'ok']);
   

2. In LogScale, verify the event has an ISO timestamp, the expected attributes, and the #service and #env tags.

3. Log a password value and confirm it appears as [REDACTED].

4. Trigger an exception and verify its class, message, and truncated trace attributes.

5. For queue delivery, verify that the buffer flushes on the configured size or age threshold and that the Redis buffer keys drain afterwards.

6. Test an invalid token or URL. The fallback channel should receive the event and the Laravel request must continue.

Troubleshooting

• No events arrive: Check that LOGSCALE_URL contains only the base URL, that the ingest token is valid, and that the logscale channel is selected where you emit the log.
• Queue mode does not flush: Confirm Redis is the default connection, a queue worker is running, and Laravel's scheduler is invoked.
• Unexpected fields are missing: Review the recursive redaction configuration in the published config/logscale.php.
• Requests must not fail when LogScale is unavailable: Use the default sync mode or ensure your queue worker and fallback channel are monitored; failed ingestion is intentionally redirected to the fallback channel.

Source

This guide is based on the package README: ITrunsDE/laravel-logscale.