PHPackages                             devkit/log-summariser - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. devkit/log-summariser

ActiveLibrary[Logging & Monitoring](/categories/logging)

devkit/log-summariser
=====================

Groups and summarises PHP/Laravel log errors with report output

07↓100%PHP

Since May 12Pushed 4w agoCompare

[ Source](https://github.com/stuarttodd-dev/devkit-log-summariser)[ Packagist](https://packagist.org/packages/devkit/log-summariser)[ RSS](/packages/devkit-log-summariser/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

devkit-log-summariser
=====================

[](#devkit-log-summariser)

[![DevKit Logo](devkit-logo.png)](devkit-logo.png)

A small PHP tool that **groups and summarises** PHP log errors: exception type (when detectable), normalised message, **occurrence count**, **first/last** timestamps, and **collapsed duplicate stack traces** per group.

It supports two input styles:

1. **Laravel-style** (default) — Monolog lines like `[YYYY-MM-DD HH:MM:SS] channel.LEVEL: …` with multi-line exception bodies. Best for `storage/logs/laravel*.log`.
2. **Generic PHP** — Plain `PHP Warning:`, `PHP Fatal error:`, `Uncaught …`, `SQLSTATE[…]`, etc. Lines are batched from each “error” line until the next error. Handy for php-fpm/CLI or mixed `error_log` output that is **not** Laravel-blocked.

Reports: **text** (default), **JSON**, **Markdown**, or **HTML**. Write to a file with **`-o`**.

Step-by-Step Usage Guide
------------------------

[](#step-by-step-usage-guide)

Follow these steps to get started with summarizing your PHP logs using devkit-log-summariser.

### 1. Install the Tool

[](#1-install-the-tool)

You have two options to install the tool:

- **Option 1: Install as a dependency in your project** (recommended for production use):

    ```
    composer require devkit/log-summariser
    ```

    The binary will be available as `vendor/bin/devkit-log-summarise`.
- **Option 2: Clone and use locally** (for testing or development):

    ```
    git clone https://github.com/your-repo/devkit-log-summariser.git
    cd devkit-log-summariser
    composer install
    ```

    Use `php bin/devkit-log-summarise` instead of `vendor/bin/devkit-log-summariser` in the commands below.

### 2. Prepare Your Log File

[](#2-prepare-your-log-file)

- Ensure you have access to a log file you want to summarize.
- For Laravel applications, use files like `storage/logs/laravel.log` or `storage/logs/laravel-*.log`.
- For generic PHP logs, use files like `/var/log/php-fpm-error.log` or any error log containing PHP warnings, fatal errors, or exceptions.

### 3. Run Basic Summarization

[](#3-run-basic-summarization)

Run the tool on your log file to get a summary of grouped errors:

```
vendor/bin/devkit-log-summarise storage/logs/laravel.log
```

This will output a text-based summary to the console, showing grouped errors with occurrence counts, timestamps, and collapsed stack traces.

### 4. Customize Output Format

[](#4-customize-output-format)

Choose the output format that suits your needs:

- **Text** (default): Human-readable summary in the console.
- **JSON**: Machine-readable format for scripts or further processing.
- **Markdown**: Formatted for documentation or tickets.
- **HTML**: Interactive web page with tabs and filtering.

Examples:

```
# JSON output
vendor/bin/devkit-log-summarise -f json storage/logs/laravel.log

# Markdown output saved to a file
vendor/bin/devkit-log-summarise -f md -o summary.md storage/logs/laravel.log

# HTML output
vendor/bin/devkit-log-summarise -f html -o report.html storage/logs/laravel.log
```

### 5. Handle Different Log Types

[](#5-handle-different-log-types)

The tool supports two log formats:

- **Laravel-style** (default): Monolog-formatted logs with timestamps like `[YYYY-MM-DD HH:MM:SS]`.
- **Generic PHP**: Plain PHP error logs without the Laravel prefix.

For generic logs, specify the parser:

```
vendor/bin/devkit-log-summarise -p generic /var/log/php-fpm-error.log
```

### 6. Enable Advanced Flow Grouping

[](#6-enable-advanced-flow-grouping)

For a deeper analysis, enable flow grouping to see related log entries as "flows" (requests, jobs, etc.):

```
# Generate HTML report with flows
vendor/bin/devkit-log-summarise --flows -f html -o flows.html storage/logs/laravel.log
```

- Filter by flow type: `--flow-type=queue-job`
- Force grouping by a key: `--group-by=request_id`
- Include flow details in text output: `--flow-detail`

See the "Flow Grouping" section below for more details.

### 7. View and Share Results

[](#7-view-and-share-results)

- **Console output**: View directly in your terminal.
- **File output**: Use `-o filename` to save to a file.
- **HTML reports**: Open in a web browser for interactive exploration.
- **JSON/Markdown**: Integrate into scripts, dashboards, or documentation.

Flow Grouping (New in v2)
-------------------------

[](#flow-grouping-new-in-v2)

The tool can group related log entries into "flows" — sequences of log entries that belong to the same request, job, command, or process. Flows help identify the full lifecycle of issues rather than isolated errors.

### Flow Detection

[](#flow-detection)

Flows are detected using identifiers like:

- `request_id`, `correlation_id`, `trace_id`
- `job_uuid`, `batch_id`, `job.class`
- `command` name
- `route` or `url`
- Close timestamps for related entries

Each flow includes:

- Flow type: `request`, `queue-job`, `command`, `webhook`, `import`, `unknown`
- Start/end times and duration
- Entry count and log levels
- Main error and suggested action
- Confidence score (high/medium/low)

### Flow Options

[](#flow-options)

OptionDescription`--flows`Include flow grouping (requires `--format=html`)`--flow-detail`Include detailed flow entries in text output`--flow-type`Filter flows by type (request, queue-job, command, webhook, import, unknown)`--group-by`Force grouping by a specific key (request\_id, correlation\_id, trace\_id, job\_uuid, batch\_id, command, route, user\_id, tenant\_id)### Flow Examples

[](#flow-examples)

```
# HTML report with flows
vendor/bin/devkit-log-summarise --flows --format=html -o report.html storage/logs/laravel.log

# Only queue job flows
vendor/bin/devkit-log-summarise --flows --format=html --flow-type=queue-job storage/logs/laravel.log

# Force grouping by user_id
vendor/bin/devkit-log-summarise --flows --format=html --group-by=user_id storage/logs/laravel.log

# Text output with flow details
vendor/bin/devkit-log-summarise --flows --flow-detail storage/logs/laravel.log
```

The HTML report provides interactive filtering, searching, and flow expansion with full details.

Requirements
------------

[](#requirements)

- PHP 8.3+
- Composer

Try it in this repository
-------------------------

[](#try-it-in-this-repository)

From the project root (after dependencies are installed):

```
cd /path/to/devkit-log-summariser
composer install
```

**1. Laravel-style sample** (timestamp blocks, stacks):

```
php bin/devkit-log-summarise tests/fixtures/logs/typeerror_repeat.log
php bin/devkit-log-summarise tests/fixtures/logs/sqlstate_repeat.log
```

**2. Generic PHP sample** (no `local.ERROR` prefix):

```
php bin/devkit-log-summarise --parser=generic tests/fixtures/logs/generic_php.log
```

**3. JSON / Markdown** (e.g. for scripts or a ticket):

```
php bin/devkit-log-summarise -f json tests/fixtures/logs/sqlstate_repeat.log
php bin/devkit-log-summarise --parser=generic -f md -o /tmp/summary.md tests/fixtures/logs/generic_php.log
```

**4. Run the test suite / quality checks** (optional):

```
composer run tests
composer run standards:check
```

Install as a dependency
-----------------------

[](#install-as-a-dependency)

```
composer require devkit/log-summariser
```

The binary is published as `vendor/bin/devkit-log-summarise` when this package is required in another project.

Usage (any install)
-------------------

[](#usage-any-install)

```
vendor/bin/devkit-log-summarise [options]  [ ...]
```

### Main options

[](#main-options)

OptionShortDescription`--parser``-p``laravel` (default) or `generic``--format``-f``text` (default), `json`, `md`, `markdown`, or `html``--output``-o`Write the report to this file instead of stdout`--flows`Include flow grouping (requires `--format=html` or `--flow-detail`)`--flow-detail`Include detailed flow entries in text output`--flow-type`Filter flows by type`--group-by`Force grouping by a specific keyExamples:

```
vendor/bin/devkit-log-summarise storage/logs/laravel.log
vendor/bin/devkit-log-summarise -p generic /var/log/php-fpm-error.log
vendor/bin/devkit-log-summarise -f json -o report.json app1.log app2.log
vendor/bin/devkit-log-summarise --flows --format=html -o flows.html storage/logs/laravel.log
```

Log format notes
----------------

[](#log-format-notes)

- **Laravel / Monolog**: each entry is expected to start with a line beginning `[YYYY-MM-DD HH:MM:SS]`. The following lines belong to the same entry until the next such line.
- **Generic**: a new group starts on lines that look like PHP or framework errors (e.g. `PHP Warning:`, `PHP Fatal error:`, `SQLSTATE[`, `Uncaught`, `*Exception:`, or messages containing `Undefined array key` / `Undefined index` when not prefixed with `PHP Warning`). Non-matching lines are skipped until the next error starter; continuation lines (stack `#0`, `thrown in`, etc.) are kept with the preceding error.

Example output (text)
---------------------

[](#example-output-text)

```
TypeError: Return value must be of type int, string returned in /app/Foo.php:10 — 3 occurrences
  First: 2024-01-10 10:00:01  Last: 2024-01-10 12:00:00
  Stack (most common duplicate):
    #0 /app/Bar.php(5): Foo->x()
    …

```

Development
-----------

[](#development)

```
composer install
composer run tests
composer run standards:check
```

Licence
-------

[](#licence)

MIT

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance62

Regular maintenance activity

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/54860041?v=4)[Stuart Todd](/maintainers/stuarttodd-dev)[@stuarttodd-dev](https://github.com/stuarttodd-dev)

---

Top Contributors

[![stuarttodd-dev](https://avatars.githubusercontent.com/u/54860041?v=4)](https://github.com/stuarttodd-dev "stuarttodd-dev (1 commits)")

### Embed Badge

![Health badge](/badges/devkit-log-summariser/health.svg)

```
[![Health](https://phpackages.com/badges/devkit-log-summariser/health.svg)](https://phpackages.com/packages/devkit-log-summariser)
```

###  Alternatives

[psr/log

Common interface for logging libraries

10.4k1.2B10.8k](/packages/psr-log)[open-telemetry/api

API for OpenTelemetry PHP.

1938.5M259](/packages/open-telemetry-api)[open-telemetry/sdk

SDK for OpenTelemetry PHP.

2326.5M315](/packages/open-telemetry-sdk)[illuminated/console-logger

Logging and Notifications for Laravel Console Commands.

8676.7k](/packages/illuminated-console-logger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)