Alkin Veysal

Posted on Oct 10

Applying Kaizen Thinking to Symfony Debugging

#symfony #php #kaizen #lean

A small open-source experiment in understanding recurring log issues, documenting investigations, and reviewing improvements.

Introducing Novora KaizenBundle 1.0 — a small, Lean-inspired approach to investigating recurring application issues.

When working on a Symfony application, logs are often the first place we look when something goes wrong.

We find an exception, investigate it, make a correction, and move on.

But sometimes the same issue returns. Or we discover that a particular warning has been appearing for days without anyone noticing how frequently it occurs.

That made me interested in a simple question:

Could we make the process of identifying, investigating, and reviewing recurring problems a little more structured, without introducing another monitoring platform?

This question led to Novora KaizenBundle, a small open-source package for Symfony.

Version 1.0 is now available on Packagist.

The idea behind the bundle

In Lean thinking, Kaizen describes continuous improvement through observation, analysis, and incremental changes.

These principles are not new, and neither are the techniques used in this bundle.

Pareto analysis, Ishikawa diagrams, the 5 Whys, and PDCA have existed for a long time. Error grouping and monitoring are also well-established areas of software engineering.

The intention here is not to reinvent them or replace existing tools.

Instead, I wanted to explore how a few of these ideas might fit into an everyday Symfony troubleshooting workflow.

The result is a deliberately small application-level tool with three main steps.

1. Identify recurring patterns

Novora KaizenBundle reads existing Monolog log files and groups records using fingerprints derived from their severity, channel, and message.

It applies limited normalization to certain dynamic values, such as UUIDs and timestamps, before grouping.

The dashboard uses a Pareto-style chart to show which patterns occur most frequently within the available log sample.

This can help answer a modest but useful question:

Which recurring technical symptoms might deserve attention first?

Frequency is not the same as importance. A rarely occurring exception may have a far greater impact than a frequently logged warning.

The chart is a starting point for investigation, not an automatic priority decision.

2. Document the investigation

Once a recurring pattern looks worth examining, a developer can open an investigation.

The bundle provides a small workspace inspired by familiar Lean techniques:

Gemba: record what was actually observed.
Ishikawa: organize possible contributing causes.
5 Whys: explore the reasoning behind a problem.
PDCA: document the intended change, its implementation, observations, and follow-up actions.

These methods are aids, not mandatory rituals.

A small issue does not necessarily need a complete Ishikawa analysis or five written explanations.

One design decision I consider important is that a hypothesis cannot be marked as confirmed without supporting evidence.

The bundle does not discover root causes automatically. The developer remains responsible for determining whether the evidence is sufficient.

3. Review what happened after a change

Fixing an exception and observing that it no longer appears are two different things.

For investigations linked to a log fingerprint, the bundle allows a correction timestamp to be recorded.

It can then compare matching log-event counts over equal periods before and after that timestamp, using at most a 24-hour comparison window.

It also checks for later occurrences still present in the available sample.

This does not prove that a problem has been permanently resolved.

A quiet log might mean the correction helped. It might also mean the relevant operation was not executed again, or that older logs have already been rotated.

The bundle therefore reports the observed counts and limitations rather than automatically declaring success.

A small example

Consider this simplified, entirely synthetic log entry:

[2026-10-10T08:00:00+00:00] app.ERROR: Cache directory is not writable [] []

Suppose the same message appears repeatedly.

The dashboard can group those matching entries and make their frequency visible.

A developer may then open an investigation, check the actual filesystem permissions and process identity, and record the findings.

If the evidence supports a permission problem, the developer can document a corrective action.

After applying the correction, the developer records when it was made and reviews the matching log entries before and after that point.

If the same fingerprint appears again, there is a concrete reason to investigate further.

If it does not appear, the observation is recorded — but the case is not automatically considered resolved.

This example illustrates the intended workflow. It is not a production case study or evidence of measured time savings.

Keeping the implementation small

The bundle is built for PHP 8.2+ and Symfony 7.4 or 8.x.

It works with existing supported Monolog file formats, provides a small administrator interface, and stores investigations in local JSON files.

It does not require its own database schema, external APM server, or hosted telemetry service.

An optional correlation feature can attach execution identifiers to new HTTP, CLI, and Messenger log records, provided the host application has the appropriate Monolog integration.

Existing log entries are not retroactively correlated.

Installation is available through Composer:

composer require novora/kaizen-bundle:^1.0

The bundle must then be registered and configured in the Symfony application. The administrator routes require authentication and ROLE_ADMIN access, and the configured log and investigation directories need appropriate filesystem permissions.

The complete setup instructions are available in the README.

What version 1.0 does not do

There are important limitations worth making clear.

The bundle reads a bounded portion of a configured log file — 2 MiB by default — rather than collecting complete application history.

Its fingerprinting is heuristic. Different errors may occasionally be grouped together, while variations of the same underlying problem may form separate groups.

Its before-and-after comparison uses observed log counts, not traffic-normalized failure rates.

It does not provide distributed tracing, automatic root-cause analysis, alerting, or multi-server monitoring.

Investigation storage is local and intended for a single shared-writer environment. Display redaction is best-effort and should never be treated as permission to log credentials or personal information.

These are conscious limitations of the first version, not capabilities hidden behind a configuration option.

For many applications, an established monitoring or error-tracking platform will be the more appropriate choice.

Why release it?

There is no shortage of debugging tools, dashboards, or methodologies.

I do not expect this bundle to change that landscape.

The idea is simply to offer another small option for Symfony developers who already have application logs and would like a structured way to move from recurring technical symptoms to documented investigations.

Version 1.0 has automated tests and has been exercised in separate Symfony 7.4/PHP 8.2 and Symfony 8.1/PHP 8.4 test applications.

That verifies specific behavior and compatibility scenarios. It does not establish how much time the tool saves in real-world development teams.

I would rather learn that from actual users than make claims I cannot support.

If the bundle proves useful, it can improve incrementally. If parts of the workflow feel unnecessary, simplifying them may be more valuable than adding new features.

That, to me, is very much in the spirit of Kaizen.