Kaizen Bundle Laravel Package

Getting Started

First, check the stack mismatch. Novora KaizenBundle v1.0.0 is a Symfony bundle, not a Laravel package — it requires Symfony 7.4/8.x, TwigBundle and SecurityBundle, and registers itself via Symfony's bundle/kernel config. There is no service provider, no config/kaizen.php, and no Artisan commands, so composer require novora/kaizen-bundle inside a Laravel app will not give you a working install even though Laravel 11/12 already ship Monolog 3.

Practical first steps for a Laravel team:

1. Read the README and confirm the config surface (log path(s), severity threshold, storage directory, security/firewall settings for the web UI).
2. Stand up the bundle in a throwaway Symfony 7.4 skeleton (or a small internal "ops" app) — composer require novora/kaizen-bundle:^1.0, enable the bundle, mount your Laravel log directory read-only into it.
3. First use case: point it at a copy of storage/logs/laravel.log (or a few laravel-YYYY-MM-DD.log files) and run the Pareto analysis to see which recurring error signatures dominate the last week. That alone answers "what should we fix first" without adding Sentry/Bugsnag.

Do not attempt step 1 in production. Treat this as an internal, authenticated tool.

Implementation Patterns

Sidecar ops app (recommended). Run the bundle as a separate Symfony container that bind-mounts storage/logs read-only from your Laravel hosts (or an S3/rsync pull of rotated logs). It stays out of the Laravel dependency graph entirely, which avoids version conflicts with Twig/Security and keeps the bundle's local file storage off your app servers.

Log ingestion pipeline. Laravel's default single/daily channels use Monolog's LineFormatter, which is close to but not identical to the default Monolog line format the bundle expects. Normalise before analysis: either add a dedicated Laravel logging channel that writes plain Monolog-formatted lines to a file the bundle reads, or pre-process with a small script. A custom channel is cleaner and is the main extension point you have:

// config/logging.php
'kaizen' => [
    'driver' => 'daily',
    'path' => storage_path('logs/kaizen.log'),
    'level' => 'warning',
    'formatter' => Monolog\Formatter\LineFormatter::class,
    'formatter_with' => ['format' => "[%datetime%] %channel%.%level_name%: %message% %context%\n"],
],

Execution correlation. The HTTP/CLI/Messenger grouping maps onto Laravel's HTTP requests, artisan invocations, and queue workers. To get correlation value, make sure your log context includes a request/job identifier consistently (e.g. push a request_id/job_uuid via a Monolog processor or Log::withContext()), otherwise the correlation view will only group by timestamp proximity.

PDCA loop in practice. Snapshot the Pareto output before a fix ("before" observations), record the corrective action and hypothesis (Ishikawa/5 Whys) in the bundle, deploy, then re-run analysis against logs from after the deploy window and compare. Keep the comparison window explicit — the bundle compares available samples, not full history, so a quiet weekend can fake a "resolved".

Where it fits in the workflow. Use it during incident review and sprint triage, not for alerting. Pair it with your existing error tracker: the tracker tells you that something broke; Kaizen's Pareto tells you which recurring class of thing is worth a ticket. Feed findings into your backlog rather than replacing observability.

Gotchas and Tips

• Not Laravel-installable. No auto-discovery, no facade, no Blade views. Any tutorial that says "composer require and go" is Symfony-specific. Budget for a sidecar app or skip the package.
• Monolog 3 only. Laravel 10 and older are on Monolog 2/3 mixes; check composer show monolog/monolog before assuming compatibility anywhere.
• Log format drift is the #1 failure mode. Laravel's daily channel rotates and its formatter includes %context%/%extra% arrays; multi-line stack traces also break line-based pattern grouping. Test the Pareto output against known log content before trusting counts.
• No database = local files. Investigations live wherever the bundle's storage dir points. In a container that means they vanish on redeploy — mount a volume. There is also no concurrency story: two people editing the same investigation will last-write-wins.
• Sample bias. The bundle analyses what's on disk. Laravel's daily retention (LOG_DAILY_DAYS, default 14) means your "before" data can rotate away mid-investigation — archive logs before starting a PDCA cycle.
• Container/JSON logging blind spot. If you log to stderr as JSON for a log aggregator (common on Kubernetes/Lambda), there may be no file on disk to analyse. You'll need to export from the aggregator into Monolog-formatted files first.
• PII and secrets. Logs contain them. Run the bundle behind auth (SecurityBundle firewall + internal network), never expose the UI publicly, and be careful about copying production logs onto laptops.
• Severity filtering is your friend. Default to error/critical first; debug-level noise will swamp the Pareto chart and produce meaningless top patterns.
• Set expectations correctly. As the release notes state, this does not determine root causes or prove resolution — it's a structured notebook over log samples. It complements, and does not replace, error tracking or APM.
• Extension points are limited. Realistically you extend it through (a) custom Monolog channels/formatters feeding it better input, and (b) custom processors adding correlation context. Don't plan on overriding bundle internals; pin ^1.0 and watch the changelog for v1.x breakage.