Laravel LogSnag

A full-featured Laravel integration for LogSnag's real-time event tracking API. Track events, monitor metrics, identify users, and pipe your Laravel logs straight to LogSnag.

Requirements

• PHP 8.2+
• Laravel 11 or 12

Installation

composer require pgtruesdell/laravel-logsnag

Publish the config file:

php artisan vendor:publish --tag="laravel-logsnag-config"

Add your LogSnag credentials to .env:

LOGSNAG_TOKEN=your-api-token
LOGSNAG_PROJECT=your-project-slug

Configuration

The published config file (config/logsnag.php) contains:

return [
    // Your LogSnag project slug
    'project' => env('LOGSNAG_PROJECT', 'my-laravel-app'),

    // Default channel for the Monolog driver
    'channel' => env('LOGSNAG_CHANNEL', 'app-events'),

    // Your LogSnag API token
    'token' => env('LOGSNAG_TOKEN', ''),

    // Icon mapping for the Monolog driver (keyed by Monolog level name)
    'icons' => [
        'Debug'     => 'ℹ️',
        'Info'      => 'ℹ️',
        'Notice'    => '📌',
        'Warning'   => '⚠️',
        'Error'     => '⚠️',
        'Critical'  => '🔥',
        'Alert'     => '🔔️',
        'Emergency' => '💀',
    ],
];

Usage

The package provides three ways to interact with LogSnag: helper functions, the Facade, or by resolving the Logsnag class from the container. All three offer the same API.

Log Events

Track events happening in your application.

use PGT\Logsnag\Facades\Logsnag;

// Minimal
Logsnag::log(channel: 'waitlist', event: 'User Signed Up');

// With all options
Logsnag::log(
    channel: 'billing',
    event: 'Subscription Renewed',
    description: 'Pro plan renewed for another year.',
    icon: '💳',
    notify: true,
    tags: ['plan' => 'pro', 'cycle' => 'yearly'],
    parser: \PGT\Logsnag\Enums\Parser::Markdown,
    userId: 'user-123',
    timestamp: now()->subMinutes(5)->timestamp,
);

Or with the helper function:

logsnag(
    channel: 'waitlist',
    event: 'User Signed Up',
    description: 'A new user joined the waitlist.',
    icon: '🎉',
);

Parameters:

Insights

Create or set a metric value.

use PGT\Logsnag\Facades\Logsnag;

Logsnag::insight(title: 'Total Users', value: 1250, icon: '👥');
Logsnag::insight(title: 'MRR', value: 14999.99, icon: '💰');
Logsnag::insight(title: 'Status', value: 'Operational');

Or with the helper:

insight(title: 'Total Users', value: 1250, icon: '👥');

Parameters:

Mutate Insights

Increment or decrement an existing metric without knowing its current value.

use PGT\Logsnag\Facades\Logsnag;

// Increment
Logsnag::mutateInsight(title: 'API Calls', incrementBy: 1);

// Decrement
Logsnag::mutateInsight(title: 'Open Tickets', incrementBy: -1);

// Float values
Logsnag::mutateInsight(title: 'Revenue', incrementBy: 49.99, icon: '💰');

Or with the helper:

mutate_insight(title: 'API Calls', incrementBy: 1);

Parameters:

Identify Users

Associate properties with a user for user-level analytics.

use PGT\Logsnag\Facades\Logsnag;

Logsnag::identify(userId: 'user-123', properties: [
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
    'plan' => 'enterprise',
    'company' => 'Acme Inc.',
]);

Or with the helper:

identify(userId: 'user-123', properties: [
    'name' => 'Jane Doe',
    'plan' => 'enterprise',
]);

Parameters:

Monolog Integration

Route your Laravel logs to LogSnag by adding a custom channel to config/logging.php:

'channels' => [
    // ...

    'logsnag' => [
        'driver' => 'custom',
        'via' => \PGT\Logsnag\Logger\LogsnagLogger::class,
        'level' => 'error', // Minimum log level to send
    ],
],

Then use it like any other log channel:

use Illuminate\Support\Facades\Log;

Log::channel('logsnag')->info('User logged in', ['user_id' => 123]);
Log::channel('logsnag')->error('Payment failed', ['order_id' => 456]);

You can also add it to your stack channel to send logs to LogSnag alongside your other drivers.

Monolog driver behavior:

• Uses the logsnag.channel config value as the LogSnag channel name
• Maps log levels to emoji icons via the logsnag.icons config
• Automatically enables notifications for Error level and above
• Appends log context as formatted JSON in the event description
• Respects the level setting to filter out lower-priority logs

Error Handling

All API methods throw PGT\Logsnag\Client\LogsnagClientException on failure. The exception includes the HTTP response for debugging:

use PGT\Logsnag\Client\LogsnagClientException;
use PGT\Logsnag\Facades\Logsnag;

try {
    Logsnag::log(channel: 'app', event: 'Something');
} catch (LogsnagClientException $e) {
    // $e->getMessage() contains the error details
    // $e->response contains the HTTP response (if available)
}

API Reference

This package covers the full LogSnag API:

Testing

composer test

Code Quality

# Static analysis
composer analyse

# Code formatting
composer format

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

• Paul Grant Truesdell, II
• All Contributors

License

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