shadowbane/laravel-gelf-logger

A custom Laravel Monolog logger for sending logs to Graylog via GELF protocol

v2.0.0 2026-03-14 06:55 UTC

Requires

• php: ^8.2
• ext-json: *
• graylog2/gelf-php: ^2.0
• monolog/monolog: ^3.0

Requires (Dev)

• laravel/pint: ^1.0
• orchestra/testbench: ^9.0 || ^10.0
• phpstan/phpstan: ^1.8

MIT

• Shadowbane

• log
• php
• monolog
• logger
• formatter
• laravel
• handler
• graylog
• gelf
• gelf-php
• gelf-logger

README

A custom Laravel Monolog logger for sending logs to Graylog via the GELF (Graylog Extended Log Format) protocol.

Features

• Send Laravel logs directly to Graylog via GELF protocol
• Supports both UDP and TCP transports
• Automatic exception tracking with stack traces
• Custom log context support with additional GELF fields
• Configurable Monolog processors (Git, Memory, Web, Load Average, Tags)
• Configurable log levels
• Custom GELF formatter with service and hostname metadata
• Laravel auto-discovery support

Requirements

• PHP ^8.2
• Laravel 11.x or higher
• ext-json
• graylog2/gelf-php ^2.0
• monolog ^3.0

Installation

Install the package via Composer:

composer require shadowbane/laravel-gelf-logger

The service provider will be automatically registered via Laravel's package auto-discovery.

Configuration

Environment Variables

Add the following to your .env file:

GELF_LOGGER_HOST=127.0.0.1
GELF_LOGGER_PORT=12201
GELF_LOGGER_TRANSPORT=udp
GELF_LOGGER_LEVEL=warning
GELF_LOGGER_TAGS=

Configuration Options

Variable	Description	Default
GELF_LOGGER_HOST	Graylog server hostname or IP address	127.0.0.1
GELF_LOGGER_PORT	GELF input port on the Graylog server	12201
GELF_LOGGER_TRANSPORT	Transport protocol (udp or tcp)	udp
GELF_LOGGER_LEVEL	Minimum log level (debug, info, notice, warning, error, critical, alert, emergency)	warning
GELF_LOGGER_TAGS	Comma-separated extra tags for Graylog stream filtering	(empty)

Publishing Configuration

To customize processors or other advanced settings, publish the config file:

php artisan vendor:publish --tag=gelf-logger-config

This creates config/gelf-logger.php where you can modify the processor list and other options.

Laravel Logging Configuration

The package automatically registers the gelf channel. You can add it to your logging stack in config/logging.php:

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['single', 'gelf'],
    ],
],

Or use it as the default log channel:

LOG_CHANNEL=gelf

Usage

Basic Logging

Use the gelf channel to send logs to Graylog:

use Illuminate\Support\Facades\Log;

Log::channel('gelf')->info('User logged in', [
    'user_id' => 123,
    'ip_address' => '192.168.1.1',
]);

Log::channel('gelf')->error('Payment failed', [
    'order_id' => 456,
    'amount' => 99.99,
]);

Exception Logging

When logging exceptions, pass the exception in the context array with the key exception:

try {
    // Your code
} catch (\Exception $e) {
    Log::channel('gelf')->error('Failed to process order: ' . $e->getMessage(), [
        'exception' => $e,
        'order_id' => 123,
        'user_id' => 456,
    ]);
}

The formatter will automatically extract and flatten exception data into GELF additional fields:

• exception_class — The exception class name
• exception_message — The exception message
• exception_code — The exception code
• exception_file — File and line where the exception occurred
• exception_trace — Full stack trace (when available)

Log Context & the extras Field

All custom context data you pass to a log call is grouped into a single extras JSON field in Graylog (rather than scattered as individual top-level fields). This keeps Graylog fields clean and makes Grafana dashboard building easier across multiple apps.

Log::channel('gelf')->warning('High memory usage', [
    'memory_used' => '512MB',
    'memory_limit' => '256MB',
    'server' => 'web-01',
]);

In Graylog, this appears as:

{
  "extras": "{\"memory_used\":\"512MB\",\"memory_limit\":\"256MB\",\"server\":\"web-01\"}"
}

Exception data (exception_* fields) is not included in extras — it stays as individual top-level fields for easy searching.

Laravel Context Integration

Data added via Laravel's Context facade is automatically included in the extras field alongside your custom context. This is useful for request tracing across logs.

// In AppServiceProvider::boot() or middleware
use Illuminate\Support\Facades\Context;

Context::add('request_id', uniqid());

Now every log entry in that request will include the data in extras:

{
  "extras": "{\"user\":{...},\"request_id\":\"6614a3b2e4f01\"}"
}

This allows you to correlate all log entries from a single request by searching for the value in Graylog.

Tags

Tags are used by Graylog for stream routing — stream rules can require specific tags to be present for a log to be routed to a particular stream.

The glfapp tag is always included automatically. This tag is required by Graylog stream rules to identify logs coming from Laravel applications using this package.

You can add extra per-app tags via the GELF_LOGGER_TAGS environment variable:

# Single tag
GELF_LOGGER_TAGS=siakad-btp

# Multiple tags (comma-separated)
GELF_LOGGER_TAGS=siakad-btp,academic

This is useful when multiple applications send logs to the same Graylog server — you can filter by app within a stream.

Processors

The package includes several Monolog processors by default:

Processor	Description
GitProcessor	Adds current Git branch and commit hash
MemoryUsageProcessor	Adds current memory usage
MemoryPeakUsageProcessor	Adds peak memory usage
LoadAverageProcessor	Adds system load average
WebProcessor	Adds HTTP request data (URL, method, IP, referrer)
TagProcessor	Adds tags (glfapp + your custom tags)

Customizing Processors

After publishing the config file, you can modify the processor list:

// config/gelf-logger.php
'processors' => [
    \Monolog\Processor\MemoryUsageProcessor::class,
    \Monolog\Processor\WebProcessor::class,
],

Note: You don't need to add TagProcessor to the processors list — it is always included automatically with glfapp and any tags from GELF_LOGGER_TAGS.

GELF Message Structure

Each log message sent to Graylog includes:

Core Fields

Field	Description
short_message	The log message
host	System name (from Monolog)
level	Syslog priority level (0-7)
timestamp	Log timestamp
facility	The log channel name
service	Application name (from config('app.name'))
hostname	Server hostname (from gethostname())
log_status	Human-readable log level name

Processor Fields (individual top-level fields)

Field	Source
tags	TagProcessor — always includes glfapp
git_branch, git_commit	GitProcessor
memory_usage, memory_peak_usage	MemoryUsageProcessor, MemoryPeakUsageProcessor
load_average	LoadAverageProcessor
url, ip, http_method, server, referrer	WebProcessor

Exception Fields (individual top-level fields)

Field	Description
exception_class	Exception class name
exception_message	Exception message
exception_code	Exception code
exception_file	File and line where the exception occurred
exception_trace	Full stack trace

Extras Field (single JSON field)

Field	Description
extras	JSON string containing all user-passed context data and Laravel Context::add() data

The extras field groups all custom data into one place, keeping Graylog fields clean and Grafana dashboards consistent across multiple applications.

Log Level Mapping

Monolog levels are mapped to GELF/syslog priorities:

Monolog Level	GELF Priority	Syslog Equivalent
Emergency	0	Emergency
Alert	1	Alert
Critical	2	Critical
Error	3	Error
Warning	4	Warning
Notice	5	Notice
Info	6	Informational
Debug	7	Debug

Graylog Setup

To receive logs from this package, your Graylog server needs a GELF input configured:

1. Go to System → Inputs in the Graylog web interface
2. Select GELF UDP (or GELF TCP if using TCP transport) from the dropdown
3. Click Launch new input
4. Set the port to 12201 (or your configured port)
5. Save and start the input

Ensure the port is accessible from your Laravel application server.

Testing

Test your Graylog integration using the included Artisan command:

php artisan gelf:send-test-exception

This command sends a test exception to the configured GELF server and confirms success.

Development

Code Style

Format code with Laravel Pint:

vendor/bin/pint

Static Analysis

Run PHPStan for static analysis:

vendor/bin/phpstan analyze

License

This package is open-sourced software licensed under the MIT license.

Credits

• Shadowbane

Support

If you discover any issues, please open an issue on the GitHub repository.