Laravel SDK

Install

composer require mybeast/logs-laravel

Laravel finds the package by itself. To change a setting that has no .env line, such as scrub or batch_size, publish the config to config/mybeast-logs.php:

php artisan vendor:publish --tag=mybeast-logs-config

The .env lines

LOG_STACK=single,mybeast
MYBEAST_LOGS_URL=https://services.my-beast.com/logs
MYBEAST_LOGS_SECRET=sk_…
MYBEAST_LOGS_ENVIRONMENT=production

Missing or malformed values switch the SDK off: without an http or https address and a server secret that looks like one, the channel takes lines and keeps none. It never throws at boot and never breaks a page.

Configuration

Every key of config/mybeast-logs.php, with the .env line that sets it where there is one:

Channels and levels

The SDK adds a log channel called mybeast, unless config/logging.php has one of that name already. Put it in the stack with LOG_STACK=single,mybeast: each line goes to Logs and on to the stack's other channels, as before. Its level is MYBEAST_LOGS_LEVEL, the mildest it takes.

Lines of this channel arrive in Logs as channel app. For a channel of its own name, add one with the mybeast driver:

// config/logging.php, under 'channels'
'payments' => [
    'driver' => 'mybeast',
    'name' => 'payments',
    'level' => 'info',
],

Log::channel('payments')->error('The bank answered 503', ['invoice' => $invoice]);

That line arrives as channel payments, which the search can narrow to. A channel's level is its mildest; left out, it is debug. A name may hold letters, digits and ._:/-, up to 64; anything else becomes -.

How lines are sent

1. Written to the spool. A line is one append to a file in spool_path: no network, no database. A request waits for nothing else.
2. Sent from there right after the response has gone out, after each queued job, and by the scheduler every ship_every_seconds. After a response or a job it sends at most every 2 seconds per server, and not while the service is failing: then the scheduler alone keeps trying.
3. In batches of batch_size lines, gzipped, oldest first. A batch leaves the spool only once the service has said it has it, and each line carries an id the service stores once, so a batch sent twice is harmless.
4. While the service is away, the lines wait in order and go when it is back. The spool may grow to spool_max_mb; past that, new lines aren't kept until there is room again, and a line then says from when to when.

The SDK says what it does in your app's other log channels, in lines that start with My Beast logs:: when sending starts to fail and when it works again, when the service refuses a line, and once a month when the project's lines for the month are used up. They stay out of Logs, except the line that says the spool was full, which arrives as channel mybeast-logs.

What each line carries

• Its level, its time to the microsecond, its message and its context, scrubbed.
• The environment, the release, the host and the channel, from the settings above. The release is MYBEAST_LOGS_RELEASE, else APP_RELEASE, else the git commit read from .git.
• The request id: the same on every line of one HTTP request and of the jobs it queued. See Read one request's lines.
• What was running, without values: GET /invoices/{invoice}/send, job App\Jobs\SendInvoice, artisan invoices:remind.

In the context:

• An Eloquent model is its class and key only, never its attributes.
• An exception is its class, message, code, file and line, the first 15 frames of its trace and the exception before it. Your app's own paths are relative to its root.
• Dates are ISO 8601, enums their value or name, and an object that can't be turned into data is its class name.
• Over 16 KiB as JSON, the context is replaced by a note of its size, keeping the exception when it fits. A message over 32 KiB is cut.

Under Octane, each request starts with a request id of its own.

Artisan commands

The SDK puts mybeast:logs-ship on the scheduler itself, without overlapping runs. What mybeast:logs-status shows, row by row, is in Troubleshooting.

The facade

The channel needs no code: Log::info() is all your app writes. The facade, MyBeast\Logs\Laravel\Facades\Logs, is for the rest:

use MyBeast\Logs\Laravel\Facades\Logs;

$id = Logs::requestId();

scrubUsing() belongs in a service provider's boot(). Its rules, and the patterns under scrub, are in Data and privacy.

Testing

Switch the SDK off in your test suite, so tests write no spool and send nothing:

<!-- phpunit.xml, in <php> -->
<env name="MYBEAST_LOGS_ENABLED" value="false"/>

Off, the channel takes lines and keeps none, and LOG_STACK can stay as it is. The SDK has no fake of its own: to check what your code logs, use Laravel's Log facade in your tests as you would without it.