Laravel Monitoring Laravel Package

Getting Started

This release (1.4.3) is the first one that makes the package viable on a modern stack: Laravel 10 support is now official, and the shell arithmetic was moved off bc onto awk. If you evaluated the package before and bounced off version constraints or “works on my Mac, not in the container” behaviour, re-evaluate now.

Minimal path to a first useful result:

1. Confirm the runtime matrix. Laravel 10 implies PHP 8.1+. Verify your app, your queue workers, and any container image all satisfy that, then composer require and check composer why-not if the constraint refuses to resolve — the usual culprit is a transitive dependency pinned below Laravel 10, not this package.
2. Publish and read the config first. Run the package’s publish command and read the whole config file before writing a single condition. Alerting rules are the part you will actually live with, and defaults here are easy to inherit blindly.
3. Verify the shell layer. Because the package now shells out to awk, confirm awk is present in every environment that runs it: local, CI, staging, production, and any Alpine/BusyBox container. It is on virtually every base image, but a scratch/distroless image or a hardened container with a trimmed filesystem will fail loudly at the worst possible time.
4. First use case: one non-critical condition on one host. Pick a metric you already understand (disk usage, load average), wire it to a condition, route the alert to a channel you personally read, and break it on purpose. Confirm the alert fires and that it clears. Only then add the second condition.

Where to look when something is wrong: the config file for threshold evaluation, then the package’s log output, then the shell command it actually executed. The 1.4.3 fix was specifically in condition-based alerting, so that code path is the newest and least battle-tested part of the package.

Implementation Patterns

Treat conditions as code, not config drift. This package’s value is entirely in its alerting conditions, and conditions rot silently. Keep them in version control, review changes to them in PRs, and name them after intent (disk-usage-warning, not check-3) so an alert at 03:00 is self-explanatory.

One condition, one actionable owner. The most common failure mode for condition-based alerting is a single catch-all channel where four different teams learn to ignore everything. Route each condition to the channel of the person who can fix it. If you cannot name that person, the condition should not exist.

Pair every condition with an explicit clear path. Since this release fixes condition alerting, re-verify both halves: that the alert fires when the threshold is crossed and that it resolves when the metric recovers. An alert that fires correctly but never clears is worse than no alert — it trains people to dismiss notifications. Test the recovery path in staging by forcing the metric back under threshold.

Use Laravel 10’s scheduling for the evaluation cadence, and keep the schedule boring. Run evaluations from the scheduler at a fixed interval rather than ad hoc. Pick a cadence slower than your metric’s natural noise (do not page on a single 5-second spike) and faster than the time it takes to become a real incident. Document the chosen interval next to the condition — future you will want to know why it is 2 minutes and not 30 seconds.

Layer it under your existing observability, not instead of it. This is a good fit for host-level or app-level checks you control from Laravel, and for internal notifications. It is not a replacement for an external uptime monitor — a process that runs inside the app cannot reliably tell you the app is down. Keep at least one check that lives outside your infrastructure.

Integration tip: route through Laravel’s notification layer where possible. If the package dispatches Laravel notifications, you inherit mail/Slack/webhook channels, Notifiable routing, and queueing for free. Favour that over bespoke curl-in-a-condition logic, which will not retry and will not be observable.

Roll it out per host, not globally. Enable on one production node, live with it for a week, tune thresholds against real data, then roll out. Thresholds guessed in advance are almost always wrong in both directions.

Gotchas and Tips

• awk vs bc: the fix is real, but watch the edges. Moving arithmetic from bc to awk removes a dependency that minimal images lack — good news for Docker/Alpine deploys. The trade-off is that you are now depending on whichever awk implementation is installed (gawk, mawk, or BusyBox awk). BusyBox awk is POSIX-ish but not identical, particularly around number formatting and precision. If a threshold comparison behaves differently between your laptop and production, this is the first thing to check.
• Your own custom scripts may still need bc. The package no longer requires it, but if you extended it with your own condition scripts that shell out to bc, those are untouched. Grep your custom scripts for bc before removing it from your image.
• Re-test alerting after upgrading. “Fixed alerting on conditions” means pre-1.4.3 condition alerts may have been firing at the wrong time, not firing at all, or not clearing. After upgrading, deliberately trigger each condition once and confirm behaviour. Also expect the opposite risk: conditions that were silently dead may now start firing legitimately, which looks like an alert storm on upgrade day. Warn whoever is on call.
• Pin the version and read the diff before jumping. Even a patch release touching alerting deserves a five-minute read of the actual changes. Upgrade on staging first; alerting bugs are among the few classes of bug that are worse than no alerting.
• Debugging tip: reproduce the shell command by hand. When a condition misbehaves, the fastest path is to extract the exact command the package runs and execute it in the same environment (same user, same PATH, same container) rather than debugging through the package. Divergence between your interactive shell and the scheduler’s environment — PATH, locale, LC_NUMERIC affecting decimal separators — is a classic cause of “works when I run it” failures.
• Beware locale-dependent number formatting. If your servers run a non-C locale, decimal commas can break threshold comparisons in shell arithmetic. Pin LC_ALL=C in the environment the evaluations run under and much of this class of bug disappears.
• Do not run the evaluation as an unprivileged user and assume it can read what it needs. Metrics like disk or process counts may require access the web user does not have. Test as the actual runtime user, not as your deploy account.
• Extension points to prefer: extra conditions and custom notification channels are stable, supported surfaces. Forking the condition evaluation logic is not — and this release proves it, since anyone who forked around the bc call or the alerting behaviour now has to reconcile that manually.
• Keep an eye on volume. These packages are cheap to add and expensive to maintain at scale. If you find yourself with more than a handful of conditions per host, look at whether a dedicated metrics/alerting system is the better home before the config file becomes unmanageable.