PHPackages shadowbane/laravel-gelf-logger - 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. shadowbane/laravel-gelf-logger ActiveLibrary[Logging & Monitoring](/categories/logging) shadowbane/laravel-gelf-logger ============================== A custom Laravel Monolog logger for sending logs to Graylog via GELF protocol v2.0.0(3mo ago)043MITPHPPHP ^8.2 Since Jul 4Pushed 3mo ago1 watchersCompare [ Source](https://github.com/shadowbane/laravel-gelf-logger)[ Packagist](https://packagist.org/packages/shadowbane/laravel-gelf-logger)[ Docs](https://github.com/shadowbane/laravel-gelf-logger)[ RSS](/packages/shadowbane-laravel-gelf-logger/feed)WikiDiscussions main Synced today READMEChangelogDependencies (10)Versions (3)Used By (0) Laravel GELF Logger =================== [](#laravel-gelf-logger) A custom Laravel Monolog logger for sending logs to Graylog via the GELF (Graylog Extended Log Format) protocol. [![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT) Features -------- [](#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 ------------ [](#requirements) - PHP ^8.2 - Laravel 11.x or higher - ext-json - graylog2/gelf-php ^2.0 - monolog ^3.0 Installation ------------ [](#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 ------------- [](#configuration) ### Environment Variables [](#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 [](#configuration-options) VariableDescriptionDefault`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 [](#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 [](#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 ----- [](#usage) ### Basic Logging [](#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 [](#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 [](#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 [](#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) 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 ---------- [](#processors) The package includes several Monolog processors by default: ProcessorDescription`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 [](#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 ---------------------- [](#gelf-message-structure) Each log message sent to Graylog includes: ### Core Fields [](#core-fields) FieldDescription`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) [](#processor-fields-individual-top-level-fields) FieldSource`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) [](#exception-fields-individual-top-level-fields) FieldDescription`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) [](#extras-field-single-json-field) FieldDescription`extras`JSON string containing all user-passed context data and Laravel `Context::add()` dataThe `extras` field groups all custom data into one place, keeping Graylog fields clean and Grafana dashboards consistent across multiple applications. Log Level Mapping ----------------- [](#log-level-mapping) Monolog levels are mapped to GELF/syslog priorities: Monolog LevelGELF PrioritySyslog EquivalentEmergency0EmergencyAlert1AlertCritical2CriticalError3ErrorWarning4WarningNotice5NoticeInfo6InformationalDebug7DebugGraylog Setup ------------- [](#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 ------- [](#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 ----------- [](#development) ### Code Style [](#code-style) Format code with Laravel Pint: ``` vendor/bin/pint ``` ### Static Analysis [](#static-analysis) Run PHPStan for static analysis: ``` vendor/bin/phpstan analyze ``` License ------- [](#license) This package is open-sourced software licensed under the [MIT license](LICENSE). Credits ------- [](#credits) - [Shadowbane](https://github.com/shadowbane) Support ------- [](#support) If you discover any issues, please open an issue on the [GitHub repository](https://github.com/shadowbane/laravel-gelf-logger/issues). ### Health Score 41 — FairBetter than 87% of packages Maintenance79 Regular maintenance activity Popularity10 Limited adoption so far Community7 Small or concentrated contributor base Maturity58 Maturing project, gaining track record 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. ### Release Activity Cadence Every ~983 days Total 2 Last Release 111d ago Major Versions v1.0.0 → v2.0.02026-03-14 PHP version history (2 changes)v1.0.0PHP ^8.1 || ^8.2 v2.0.0PHP ^8.2 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/6396154?v=4)[Shadowbane](/maintainers/shadowbane)[@shadowbane](https://github.com/shadowbane) --- Top Contributors [![shadowbane](https://avatars.githubusercontent.com/u/6396154?v=4)](https://github.com/shadowbane "shadowbane (5 commits)") --- Tags logphpformatterlaravelhandlerloggermonologgrayloggelfgelf-phpgelf-logger ### Code Quality Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/shadowbane-laravel-gelf-logger/health.svg) ``` [![Health](https://phpackages.com/badges/shadowbane-laravel-gelf-logger/health.svg)](https://phpackages.com/packages/shadowbane-laravel-gelf-logger) ``` ### Alternatives [hedii/laravel-gelf-logger A Laravel package to send logs to a gelf compatible backend like graylog 1363.6M12](/packages/hedii-laravel-gelf-logger)[logtail/monolog-logtail Logtail handler for Monolog 243.6M3](/packages/logtail-monolog-logtail)[yzen.dev/mono-processor This Processor will display in the logs bread crumbs by which you can more quickly and accurately identify the cause of the error. 116.1k](/packages/yzendev-mono-processor) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)