Documentation forSolarWinds Observability SaaS

Ship Laravel application logs over HTTPS (Papertrail)

You can ship Laravel application logs directly to Papertrail over HTTPS. (For other PHP applications, including Symfony, see Ship PHP application logs (Papertrail)). The setup adds one handler class and one log channel. This allows the following:

  • Each log record shows the correct System, Program, and Severity in the Logs Explorer.

  • Log records keep the plain-text message, with context appended as JSON only when present.

  • Multiline records arrive as one event.

  • Log records are sent in batches over port 443, so the setup will work behind HTTP-only firewalls.

To get a destination and token in Papertrail, add a new log destination. The ingestion token is generated along with the destination. Use the collector endpoints for your account's region:

  • HTTPS: https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/bulk

Replace <REGION> with the data center your organization uses: na-01, eu-01, or ap-01.

How Papertrail fills System, Program, and Severity

The Papertrail Logs Explorer is syslog-shaped. It shows the source in the System column, the application in the Program column, and the Severity of each event. The handler on this page wraps every log record in a standard RFC 5424 syslog header and posts the batch to the HTTPS bulk endpoint with Content-Type: application/syslog-frames. The collector reads the header of each record:

Logs Explorer category Source Laravel value
System Syslog HOSTNAME Server host name (gethostname())
Program Syslog APP-NAME APP_NAME from .env
Severity Syslog PRI Laravel log level
Message Syslog MSG Log message, context as JSON, exception stack trace

Each record is prefixed with its length in bytes (octet-counted framing), so line breaks inside a message do not split it into several events.

Requirements

To send Laravel application logs to Papertrail over HTTPS, you will need the following:

  • Laravel 10 or later (Monolog 3), PHP 8.1 or later

  • PHP curl extension (installed on almost every PHP host)

  • Outbound HTTPS (port 443) to logs.collector.<REGION>.cloud.solarwinds.com

No Composer packages are needed.

Step 1: Add the handler

Create app/Logging/SwoLogHandler.php:

<?php

namespace App\Logging;

use Illuminate\Queue\Events\JobFailed;
use Illuminate\Queue\Events\JobProcessed;
use Monolog\Handler\AbstractProcessingHandler;
use Monolog\Level;
use Monolog\LogRecord;
use Throwable;

class SwoLogHandler extends AbstractProcessingHandler
{
    private array $frames = [];
    private int $bytes = 0;

    public function __construct(private string $region, private string $token, private string $appName, int|string|Level $level = Level::Debug)
    {
        parent::__construct($level);
        $this->appName = str_replace(' ', '-', $appName);

        // Queue workers run for a long time: send each job's logs when the job ends.
        app('events')->listen([JobProcessed::class, JobFailed::class], fn () => $this->flush());
    }

    protected function write(LogRecord $record): void
    {
        // Plain-text message, then context as JSON, then PHP's own multi-line stack trace.
        $context = $record->context + $record->extra;
        $exception = $context['exception'] ?? null;
        unset($context['exception']);

        $text = $record->message;
        if ($context) {
            $text .= ' '.json_encode($context, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PARTIAL_OUTPUT_ON_ERROR);
        }
        if ($exception instanceof Throwable) {
            $text .= "\n".$exception;
        }

        // The syslog header sets Severity, System and Program. The length prefix keeps multi-line messages in one event.
        $message = sprintf('<%d>1 %s %s %s %d %s - %s',
            8 + $record->level->toRFC5424Level(),
            $record->datetime->format('Y-m-d\TH:i:s.uP'),
            gethostname(), $this->appName, getmypid(), $record->channel, $text);

        $this->frames[] = strlen($message).' '.$message;
        $this->bytes += strlen($message);

        if (count($this->frames) >= 100 || $this->bytes > 4_000_000) {
            $this->flush();
        }
    }

    public function flush(): void
    {
        if (! $this->frames) {
            return;
        }

        $ch = curl_init("https://logs.collector.{$this->region}.cloud.solarwinds.com/v1/logs/bulk");
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => implode('', $this->frames),
            CURLOPT_HTTPHEADER => ["Authorization: Bearer {$this->token}", 'Content-Type: application/syslog-frames'],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5,
        ]);
        curl_exec($ch);

        if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 202) {
            error_log('SWO log delivery failed: HTTP '.curl_getinfo($ch, CURLINFO_RESPONSE_CODE).' '.curl_error($ch));
        }

        $this->frames = [];
        $this->bytes = 0;
    }

    public function close(): void
    {
        $this->flush();
    }
}

Step 2: Add the log channel

In config/logging.php, add a swo entry to the channels array. PsrLogMessageProcessor is already imported at the top of Laravel's default config/logging.php.

'swo' => [
    'driver' => 'monolog',
    'level' => env('LOG_LEVEL', 'debug'),
    'handler' => App\Logging\SwoLogHandler::class,
    'handler_with' => [
        'region' => env('SWO_REGION', 'na-01'),
        'token' => env('SWO_TOKEN'),
        'appName' => env('APP_NAME', 'laravel'),
    ],
    'processors' => [PsrLogMessageProcessor::class],
],

Step 3: Configure .env

APP_NAME=my-app
LOG_STACK=single,swo
SWO_REGION=<REGION>
SWO_TOKEN=<TOKEN>
  • LOG_STACK=single,swo keeps the local storage/logs/laravel.log file and also sends every log to Papertrail. To send only to Papertrail, set LOG_CHANNEL=swo instead.

  • On Laravel 10, LOG_STACK does not exist yet. Add 'swo' to the channels array of the stack channel in config/logging.php.

  • APP_NAME becomes the Program. Spaces are replaced with dashes.

  • If you cache configuration in production, run php artisan config:cache after changing .env.

Step 4: Verify

Run the following:

php artisan tinker --execute="Log::info('Hello from Laravel', ['order_id' => 1234]); Log::error('Payment failed', ['exception' => new RuntimeException('Card declined')]);"

In the Logs Explorer, search for Hello from Laravel. The System column shows your server's host name, Program shows APP_NAME, and the error appears as one event with the full stack trace.

What arrives in the Logs Explorer

The Logs Explorer will show events:

Searchable attributes are extracted from each event:

Attribute Value
syslog.host, syslog.appname System and Program
syslog.msgid Laravel environment, for example production
syslog.procId PHP process ID
json.* Each context field, for example json.order_id:1234

Troubleshooting

Symptom Likely cause What to do
SWO log delivery failed: HTTP 401 in the PHP error log Wrong token, or the token belongs to a different region Copy the token again from the log destination, and check SWO_REGION.
SWO log delivery failed: HTTP 0 Resolving timed out, and requests are slow SWO_REGION contains an invalid value Use your account's region, for example na-01 or eu-01.
No logs arrive and nothing is in the PHP error log The swo channel is not used Check LOG_STACK or LOG_CHANNEL, then run php artisan config:clear.
Program shows Laravel APP_NAME is still the default Set APP_NAME in .env.

Fallback: Forward via a syslog daemon

If your application cannot connect directly to the Papertrail collector (for example, a strict outbound firewall blocks ports 6514 and 443), write logs to a local file and use the host's syslog daemon to forward them to Papertrail over TLS. Papertrail supports rsyslog on Linux and NXlog on Windows for this purpose. See Send logs using syslog (Papertrail) for configuration instructions.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.