README

Automatically create GitHub issues from your Laravel exceptions & logs. Perfect for smaller projects without the need for full-featured logging services.

Requirements

PHP ^8.3
Laravel ^11.37|^12.0
Monolog ^3.6

Features

✨ Automatically create GitHub issues from Exceptions & Logs
🔍 Group similar errors into single issues
💬 Add comments to existing issues for recurring errors
🏷️ Support customizable labels
🎯 Smart deduplication to prevent issue spam
⚡️ Buffered logging for better performance
📝 Customizable issue templates
🕵🏻‍♂️ Tracing Support (Request & User)

Showcase

When an error occurs in your application, a GitHub issue is automatically created with comprehensive error information and stack trace:

The issue appears in your repository with all the detailed information about the error:

If the same error occurs again, instead of creating a duplicate, a new comment is automatically added to track the occurrence:

Installation

Install with Composer:

composer require naoray/laravel-github-monolog

Configuration

Add the GitHub logging channel to config/logging.php:

'channels' => [
    // ... other channels ...

    'github' => [
        // Required configuration
        'driver' => 'custom',
        'via' => \Naoray\LaravelGithubMonolog\GithubIssueHandlerFactory::class,
        'repo' => env('GITHUB_REPO'),    // Format: "username/repository"
        'token' => env('GITHUB_TOKEN'),  // Your GitHub Personal Access Token

        // Optional configuration
        'level' => env('LOG_LEVEL', 'error'),
        'labels' => ['bug'],
    ],
]

Add these variables to your .env file:

GITHUB_REPO=username/repository
GITHUB_TOKEN=your-github-personal-access-token

You can use the github log channel as your default LOG_CHANNEL or add it as part of your stack in LOG_STACK.

Getting a GitHub Token

To obtain a Personal Access Token:

Go to Generate a new token (this link pre-selects the required scopes)
Review the pre-selected scopes (the repo scope should be checked)
Click "Generate token"
Copy the token immediately (you won't be able to access it again after leaving the page)
Add it to your .env file as GITHUB_TOKEN

Note: The token requires the repo scope to create issues in both public and private repositories.

Usage

Whenever an exception is thrown it will be logged as an issue to your repository.

You can also use it like any other Laravel logging channel:

// Single channel
Log::channel('github')->error('Something went wrong!');

// Or as part of a stack
Log::stack(['daily', 'github'])->error('Something went wrong!');

Advanced Configuration

Customizing Templates

The package uses Markdown templates to format issues and comments. You can customize these templates by publishing them:

php artisan vendor:publish --tag="github-monolog-views"

This will copy the templates to resources/views/vendor/github-monolog/ where you can modify them:

issue.md: Template for new issues
comment.md: Template for comments on existing issues
previous_exception.md: Template for previous exceptions in the chain

Important:

The templates use HTML comments as section markers (e.g.  and ). These markers are used to intelligently remove empty sections from the rendered output. Please keep these markers intact when customizing the templates.

If you've previously published and customized templates, you may need to republish them to get the latest structure with triage headers and collapsible sections. Compare your custom templates with the new defaults and migrate any customizations.

Available template variables:

{level}: Log level (error, warning, etc.)
{message}: The error message or log content
{class}: Exception class name
{signature}: Internal signature used for deduplication
{timestamp}: Timestamp when the error occurred (format: Y-m-d H:i:s)
{environment_name}: Environment name (e.g., production, staging) from APP_ENV
{route_summary}: HTTP method and path (e.g., "GET /api/users")
{user_summary}: User ID or "Unauthenticated"
{simplified_stack_trace}: A cleaned up stack trace
{full_stack_trace}: The complete stack trace
{previous_exceptions}: Details of any previous exceptions
{environment}: Full environment data (JSON)
{request}: Full request data (JSON)
{route}: Full route data (JSON)
{user}: Full user data (JSON)
{queries}: Recent database queries
{job}: Job context data (JSON)
{command}: Command context data (JSON)
{outgoing_requests}: Outgoing HTTP requests
{session}: Session data (JSON)
{context}: Additional context data (JSON)
{extra}: Extra log data (JSON)

Deduplication

Group similar errors to avoid duplicate issues. The package uses Laravel's cache system for deduplication storage.

'github' => [
    // ... basic config from above ...
    'deduplication' => [
        'time' => 60,        // Time window in seconds - how long to wait before creating a new issue
        'store' => null,     // Uses your default cache store (from cache.default)
        'prefix' => 'dedup', // Prefix for cache keys
    ],
]

For cache store configuration, refer to the Laravel Cache documentation.

Buffering

Buffer logs to reduce GitHub API calls. Customize the buffer size and overflow behavior to optimize performance:

'github' => [
    // ... basic config from above ...
    'buffer' => [
        'limit' => 0,        // Maximum records in buffer (0 = unlimited, flush on shutdown)
        'flush_on_overflow' => true,  // When limit is reached: true = flush all, false = remove oldest
    ],
]

When buffering is active:

Logs are collected in memory until flushed
Buffer is automatically flushed on application shutdown
When limit is reached:
- With flush_on_overflow = true: All records are flushed
- With flush_on_overflow = false: Only the oldest record is removed

Tracing

Note: Tracing is opt-in and disabled by default. To enable tracing capabilities, you must add the tracing configuration to your config/logging.php file under the github channel configuration.

The package includes optional tracing capabilities that allow you to track requests, user data, queries, and more in your logs. Enable this feature through your configuration:

'tracing' => [
    'enabled' => true,           // Master switch for all tracing
    'requests' => true,          // Enable request tracing
    'route' => true,            // Enable route tracing
    'user' => true,             // Enable user tracing
    'queries' => [               // Database query tracing
        'enabled' => true,
        'limit' => 10,           // Maximum number of queries to track
    ],
    'jobs' => true,             // Enable job context tracing
    'commands' => true,         // Enable command context tracing
    'outgoing_requests' => [    // Outgoing HTTP request tracing
        'enabled' => true,
        'limit' => 5,           // Maximum number of outgoing requests to track
    ],
    'environment' => true,      // Enable environment data collection
    'session' => true,          // Enable session data collection
    'redact' => [               // Data redaction configuration
        'headers' => [],        // Additional headers to redact (beyond defaults)
        'payload_fields' => [], // Additional payload fields to redact (beyond defaults)
        'query_bindings' => false, // Whether to redact query bindings
    ],
]

Request Tracing

When request tracing is enabled, the following data is automatically logged:

URL
HTTP Method
Route information
Headers (filtered to remove sensitive data)
Request body

Route Tracing

When route tracing is enabled, the following route information is logged:

Route name
URI pattern
Route parameters
Controller action
Middleware stack
HTTP methods

User Tracing

By default, user tracing only logs the user identifier to comply with GDPR regulations. However, you can customize the user data being logged by setting your own resolver:

use Naoray\LaravelGithubMonolog\Tracing\UserDataCollector;

UserDataCollector::setUserDataResolver(function ($user) {
    return [
        'username' => $user->username,
        // Add any other user fields you want to log
    ];
});

Note: When customizing user data collection, ensure you comply with relevant privacy regulations and only collect necessary information.

Query Tracing

When query tracing is enabled, recent database queries are logged with:

SQL statement
Query bindings (can be redacted)
Execution time
Connection name

You can limit the number of queries tracked using the limit configuration option.

Job Tracing

When job tracing is enabled, queue job context is logged including:

Job name and class
Queue name
Connection name
Attempt number
Job payload (sensitive data is redacted)

Command Tracing

When command tracing is enabled, artisan command context is logged including:

Command name
Command arguments
Command options (sensitive data is redacted)

Outgoing Request Tracing

When outgoing request tracing is enabled, HTTP requests made by your application are logged with:

Request URL and method
Response status code
Request duration
Request headers

You can limit the number of outgoing requests tracked using the limit configuration option.

Environment Tracing

When environment tracing is enabled, application environment data is collected including:

App environment and debug mode
Laravel and PHP versions
Hostname
Git commit (if configured)

Session Tracing

When session tracing is enabled, session data is logged including:

Session data (sensitive fields are redacted)
Flash data (old and new)

Data Redaction

The package automatically redacts sensitive data from headers, payloads, and query bindings. You can customize what gets redacted:

headers: Additional header names to redact beyond the default sensitive headers
payload_fields: Additional payload field names to redact beyond the default sensitive fields
query_bindings: Set to true to redact all query bindings (default: false)

Signature Generator

Control how errors are grouped by customizing the signature generator. By default, the package uses a generator that creates signatures based on exception details or log message content.

'github' => [
    // ... basic config from above ...
    'signature_generator' => \Naoray\LaravelGithubMonolog\Deduplication\DefaultSignatureGenerator::class,
]

You can implement your own signature generator by implementing the SignatureGeneratorInterface:

use Monolog\LogRecord;
use Naoray\LaravelGithubMonolog\Deduplication\SignatureGeneratorInterface;

class CustomSignatureGenerator implements SignatureGeneratorInterface
{
    public function generate(LogRecord $record): string
    {
        // Your custom logic to generate a signature
        return md5($record->message);
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

naoray / laravel-github-monolog

Maintainers

Details