graylog2 / gelf-php
A php implementation to send log-messages to a GELF compatible backend like Graylog2.
Installs: 30 524 591
Dependents: 144
Suggesters: 29
Security: 0
Stars: 410
Watchers: 15
Forks: 86
Open Issues: 12
Requires
- php: >=8.0
- psr/log: ^1|^2|^3
Requires (Dev)
- phpunit/phpunit: ^9.6|^10.1
- squizlabs/php_codesniffer: ^3.6
- vimeo/psalm: ^5.11
Provides
- psr/log-implementation: 3.0.0
- dev-master
- 2.0.x-dev
- 2.0.1
- 2.0.0
- 2.0.0-beta.1
- 1.7.1
- 1.7.0
- 1.6.5
- 1.6.4
- 1.6.3
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.5
- 1.5.4
- 1.5.3
- 1.5.2
- 1.5.1
- 1.5.0
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.0
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- 0.1.x-dev
- 0.1.0
- dev-bz/move-to-github-actions
- dev-bz/psr-log-3
- dev-1.0-legacy
- dev-2.0-old
- dev-issues/25-docs
This package is auto-updated.
Last update: 2024-12-14 21:26:15 UTC
README
A php implementation to send log-files to a gelf compatible backend like Graylog2. This library conforms to the PSR standards in regards to structure (4), coding-style (1, 2) and logging (3).
It's a loosely based on the original Graylog2 gelf-php and mlehner's fork.
Stable release and deprecation of the original graylog2/gelf-php
This implementation became the official PHP GELF library on 2013-12-19 and is now released as graylog2/gelf-php
.
The old library became deprecated at the same time and it's recommended to upgrade.
Since the deprecated library never got a stable release, we decided keep it available as v0.1
. This means:
If you have a project based on the deprecated library but no time to upgrade to version 1.0, we recommend to change your
composer.json
as following:
"require": {
// ...
"graylog2/gelf-php": "0.1.*"
// ...
}
After running an additional composer update
everything should work as expected.
A note on PHP versions before 5.6
I tried to keep backwards compatibility alive as long as possible, but it 2021 it's not feasible anymore to deal with the pain of dependency management for PHP 5.3.3 - 5.5.latest. They are EOL for many years anyway.
If you are somehow stuck on <5.6, you can use gelf-php up to version 1.6.5.
I decided against a semver-compliant increase from 1.x to 2.x on purpose.
Usage
Recommended installation via composer:
Add gelf-php to composer.json
either by running composer require graylog2/gelf-php
or by defining it manually:
"require": {
// ...
"graylog2/gelf-php": "~1.5"
// ...
}
Reinstall dependencies: composer install
Examples
For usage examples, go to /examples.
Muting connection and transport errors
Oftentimes projects run into the situation where they don't want to raise exceptions for logging-errors. Since
the standard transports like Udp, Tcp and Http can be kind of noise for fwrite/fopen errors, gelf-php provides
a IgnoreErrorTransportWrapper
. This class can decorate any AbstractTransport
and will mute all exceptions.
How this applies in practice can be seen in the advanced-example.
If you use gelf-php in conjunction with monolog/symfony, the following snippet should help you with properly setting up your logging backend.
Assuming you have a typical monolog config:
monolog: handlers: graylog: type: service id: monolog.gelf_handler level: debug
You only need to properly define the symfony-service gelf-handler
:
services: monolog.gelf_handler: class: Monolog\Handler\GelfHandler arguments: - @gelf.publisher - 'warning' #monolog config is ignored with custom service level has to be redefined here (default : debug), you should probably use parameters eg: '%gelf_level%' gelf.publisher: class: Gelf\Publisher arguments: [@gelf.ignore_error_transport] gelf.ignore_error_transport: class: Gelf\Transport\IgnoreErrorTransportWrapper arguments: [@gelf.transport] gelf.transport: class: Gelf\Transport\UdpTransport # or Tcp, Amp, Http,... arguments: [] # ... whatever is required
HHVM
While HHVM is supported/tested, there are some restrictions to look out for:
- Stream-context support is very limited (as of 2014) - especially regarding SSL - many use-cases might not work as expected (or not at all...)
fwrite
does behave a little different
The failing unit-tests are skipped by default when running on HHVM. They are also all annotated with @group hhvm-failures
.
You can force to run those failures by setting FORCE_HHVM_TESTS=1
in the environment. Therefore you can specifically check
the state of HHVM failures by running:
FORCE_HHVM_TESTS=1 hhvm vendor/bin/phpunit --group hhvm-failures
License
The library is licensed under the MIT license. For details check out the LICENSE file.
Development & Contributing
You are welcome to modify, extend and bugfix all you like. :-) If you have any questions/proposals/etc. you can contact me on Twitter (@bzikarsky) or message me on freenode#graylog2.
Tools
- composer, preferably a system-wide installation as
composer
- PHPUnit
- Optional: PHP_CodeSniffer for PSR-X-compatibility checks
Steps
- Clone repository and cd into it:
git clone git@github.com:bzikarsky/gelf-php && cd gelf-php
- Install dependencies:
composer install
- Run unit-tests:
vendor/bin/phpunit
- Check PSR compatibility:
vendor/bin/phpcs --standard=PSR2 src tests examples