Nova Logs Tool Laravel Package

Technical Evaluation

Architecture fit. This is a Laravel Nova tool — not a standalone package. It only fits an architecture that already runs Nova, and it plugs in through the standard tool registration surface (NovaServiceProvider::tools() or the tools array in config/nova.php). Its footprint is small and legible: one LogsTool subclass (boot(), menu(), cards()), a small set of routes, a controller that resolves a logs directory and reads files, and a single compiled Vue component in dist/. That is the entire integration surface, which is good news for evaluation: it can be read end-to-end in about an hour, and owned by a mid-level Laravel engineer in about a day. Architecturally it is a per-node convenience link into local log files, not a logging platform — it lists what is on disk now, on the node it runs on.

Integration feasibility. Very high, with one gating check. composer require kabbouchi/nova-logs-tool, register KABBOUCHI\LogsTool\LogsTool::make() verbatim (vendor namespace is uppercase, and PSR-4 is case-sensitive on Linux — a macOS-working install can fail on production), then php artisan config:clear and php artisan route:list | grep -i logs to confirm the route and the sidebar entry mounted. The single highest-probability adoption blocker is the laravel/nova constraint in composer.json: the package is Nova 3/4-era, last tagged v1.1.0 on 2023-02-20. Against a Nova 5 stack, you must decide up front to pin an older Nova, force with --with-all-dependencies, or fork. That decision gates everything downstream.

Technical risk. Concentrated in a handful of known failure modes, all of which are visible in the source and testable in staging:

• Whole-file reads. If the controller uses file_get_contents / Storage::get, a 100–200 MB incident-day log exhausts memory_limit or hits a gateway timeout — it fails exactly when you need it. Confirm whether reads are chunked before rollout.
• Regex parsing assumes classic single-line laravel-*.log. JSON-structured Monolog output and multi-line stack traces render poorly or are unsearchable, often without erroring.
• Destructive delete with no soft-delete, no audit trail, no policy hook. Removing the only copy of a log mid-incident is a governance incident.
• Silent-empty file list. Almost always the disk path or web-user permissions, not "no logs" — which is worse, because operators trust it mid-incident.
• Stale dist/ assets. Sidebar renders, panel is blank. The #1 post-Nova-upgrade breakage; fix with nova:publish or rebuild the fork's dist/.
• Dormant upstream. 71 stars, 0 dependents, last release Feb 2023, no documented security advisory process. Assume no upstream support.
• Access widening is a compliance change. Anyone with a Nova seat can read secrets, PII, and tokens that land in log lines.

Key questions to resolve before committing:

1. Which Laravel Nova major are we on, and does the package's constraint actually resolve?
2. Where does the app write logs (config/logging.php, logs disk in config/filesystems.php), and are any channels structured, stderr-only, or in per-service subdirectories?
3. Who should see this — every Nova seat, or a named on-call/devops group?
4. Is delete acceptable at all, or do we mount storage/logs read-only / fork the action out?
5. Single-node or multi-node estate, and what is the real log aggregator we point people to for anything spanning requests?
6. What actually lands in our logs — any secrets or PII that cannot be exposed through a Nova login?

Integration Approach

Stack fit. Laravel + Nova only. Without Nova, this package should not influence any tooling decision. With Nova, it is a near-zero-cost internal admin feature. Verify the logs path the tool browses against the directory the application actually writes to — custom channels are the most common reason the file list comes back empty or incomplete.

Compatibility and migration path. Pin the exact 1.1.0 tag and commit composer.lock. Do not treat version bumps as routine: going 0.7.0 → 1.1.0 crosses a pre-1.0 minor boundary where breaking changes are explicitly allowed. Re-resolve the lockfile, re-verify dist/ against your Nova major, and re-run worst-case input tests before anything touches production. Keep a fork branch warm and rebase it small; the extension surface is subclassing LogsTool for routes/menu, overriding controller methods for streaming or to gate delete/download, and editing the Vue component for UI.

Sequencing. Run this order and do not skip ahead:

1. Read the source first — an hour in vendor/kabbouchi/nova-logs-tool/src. Confirm path resolution, read strategy (whole-file vs. chunked), and whether delete/download are gated.
2. Check the Nova constraint and decide pin / force / fork. This is the go/no-go.
3. Install in local and staging only.
4. Gate to a named group, not to "has a Nova seat": define a viewLogsTool gate against on-call/devops and conditionally include the tool, so unauthorized engineers never see the sidebar item.
5. Scope by environment — default off in production, on for staging/local, and enabled in production only for the incident-triage case and only alongside the named group.
6. Adopt a read-only posture before the first engineer sees the panel — preferably mount storage/logs read-only to the PHP-FPM/web user so unlink() fails at the filesystem level; otherwise fork the delete (and optionally download) action out of both the route list and the Vue panel.
7. Test the worst cases in staging: a 100–200 MB log against memory_limit; a JSON Monolog log; a multi-line stack trace; a log in a non-default subdirectory.
8. Run config:clear in dev and config:cache on deploy — a cached config silently ignoring the environment guard is a nasty surprise.
9. Promote to production, then instrument adoption and escalations.

Pair, don't replace. This is a file browser, not request-level debugging. Keep Telescope (or php artisan tail) for local per-request inspection, and keep the real log platform (Loki, CloudWatch, Datadog, Sentry) for anything spanning requests or nodes. Spell the limitation out in the on-call runbook: "this tool sees one node; for anything spanning requests, use the aggregator."

Operational Impact

Maintenance. Assume upstream is dormant and plan for it. The model is "adopt and fork on a trigger," not "wait for a release." Keep an owner assigned, a fork branch rebased, and a documented trigger list: Nova major upgrade, security finding, missing feature. Because the codebase is one Tool class, a handful of routes, and one Vue component, a mid-level Laravel engineer can own it in about a day — that is the whole reason this is viable despite the maintenance signals. Budget the fork as a planned response, not an unexpected event.

Support. No SLA, no documented security advisory process, single maintainer, small community, 0 dependents. Internal support is your team's. Escalation path is the fork, not the upstream issue tracker. Compounding this: no plugin API and no policy hook, so any behavioral change (streaming reads, delete gating, UI changes) is a fork, not configuration.

Scaling. Strictly single-node. In a multi-node estate it shows one node's local files, listed as they exist on disk now — rotation and retention are entirely your responsibility. There is no aggregation, alerting, historical search, or real-time tailing. Large incident-day files are the scaling cliff: whole-file reads against memory_limit fail under exactly the conditions the tool exists for. Mitigate with aggressive rotation to cap exposed file size, or fork in a streamed reader. Raising memory_limit is an emergency stopgap, not a fix.

Failure modes to monitor and document:

• Memory exhaustion / gateway timeout on large files — the top failure mode.
• Blank panel with a rendered sidebar item — stale dist/ after a Nova bump; check browser console, then nova:publish.
• Empty file list — disk path or web-user (www-data / php-fpm / container user) permissions. Silent-empty is the dangerous variant.
• Structured JSON or multi-line traces rendering as nonsense or unsearchable — no error raised.
• Irreversible delete with no record of who did it.
• PSR-4 case mismatch — works on macOS, fails on Linux production.
• Cached config silently ignoring the environment guard.

Ramp-up. Low and fast. The first-day win is 20 minutes: open the latest laravel-YYYY-MM-DD.log, search for a request ID or exception class in the UI, download the file for offline grep when built-in search falls short — no SSH, no tail -f over a jump host. Onboard support, QA, DevOps, and on-call together, but gate membership explicitly and audit what the app writes to logs before widening access. Frame it to stakeholders as a free MIT add-on for the Nova admin already in place that cuts engineer interruptions for routine troubleshooting — an internal efficiency bet, not a platform initiative.

Success measurement. Instrument reduced "can you check the logs?" escalations, faster support triage, and adoption among support and DevOps. Do not measure it against uptime or MTTR targets it cannot serve. Usage telemetry doubles as a demand signal: if usage is high and stays confined to single-node file browsing, it earns a permanent convenience-layer role; if users immediately ask for cross-service search, alerting, or live tailing, that is the evidence to fund a real logging platform instead of extending this tool.