|
| 1 | +# zendtech/zendhq-monolog-handler |
| 2 | + |
| 3 | +This project provides a handler for [Monolog](https://seldaek.github.io/monolog/) that pushes to [ZendHQ](https://www.zend.com/products/zendphp-enterprise/zendhq) monitoring. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +```bash |
| 8 | +composer require zendtech/zendhq-monolog-handler |
| 9 | +``` |
| 10 | + |
| 11 | +### Requirements |
| 12 | + |
| 13 | +- A ZendHQ node |
| 14 | +- ZendPHP >= 7.2 |
| 15 | +- The ZendHQ extension |
| 16 | +- Monolog 2.4+ or 3.4+ |
| 17 | + |
| 18 | +## Usage |
| 19 | + |
| 20 | +The below examples demonstrate how to create a `ZendHQHandler` instance for use in writing logs with Monolog. |
| 21 | + |
| 22 | +### Default instantiation |
| 23 | + |
| 24 | +Default usage is to use Monolog/PSR-3 log levels to indicate severity. |
| 25 | +You can instantiate the provided `ZendTech\ZendHQ\MonologHandler\ZendHQHandler` class without any arguments, or with the `$level` and/or `$bubble` arguments: |
| 26 | + |
| 27 | +```php |
| 28 | +use Monolog\Logger; |
| 29 | +use ZendTech\ZendHQ\MonologHandler\ZendHQHandler; |
| 30 | + |
| 31 | +// PHP 7: |
| 32 | +// - Default level (DEBUG) and allowing bubbling: |
| 33 | +$handler = new ZendHQHandler(); |
| 34 | + |
| 35 | +// - Setting a level mask of warnings or greater only: |
| 36 | +$handler = new ZendHQHandler(null, Logger::WARNING); |
| 37 | + |
| 38 | +// - Default level (DEBUG), but disallowing bubbling |
| 39 | +$handler = new ZendHQHandler(null, Logger::DEBUG, false); |
| 40 | + |
| 41 | +// PHP 8: |
| 42 | +// - Default level (DEBUG) and allowing bubbling: |
| 43 | +$handler = new ZendHQHandler(); |
| 44 | + |
| 45 | +// - Setting a level mask of warnings or greater only: |
| 46 | +$handler = new ZendHQHandler(level: Logger::WARNING); |
| 47 | + |
| 48 | +// - Default level (DEBUG), but disallowing bubbling |
| 49 | +$handler = new ZendHQHandler(bubble: false); |
| 50 | +``` |
| 51 | + |
| 52 | +### Instantiation for usage with named rules |
| 53 | + |
| 54 | +ZendHQ custom monitoring rules will specify severity in the rule definition, so severity is ignored. |
| 55 | +To use such custom rules, provide the custom rule name when instantiating `ZendHQHandler`. |
| 56 | +The following examples target a "my_custom_rule" rule. |
| 57 | +While you _can_ provide a default level to handle, the value will not be sent to ZendHQ, and only used to determine if a message will get logged. |
| 58 | + |
| 59 | +```php |
| 60 | +use Monolog\Logger; |
| 61 | +use ZendTech\ZendHQ\MonologHandler\ZendHQHandler; |
| 62 | + |
| 63 | +// PHP 7: |
| 64 | +// - Default level (DEBUG) and allowing bubbling: |
| 65 | +$handler = new ZendHQHandler('my_custom_rule'); |
| 66 | + |
| 67 | +// - Setting a level mask of warnings or greater only: |
| 68 | +$handler = new ZendHQHandler('my_custom_rule', Logger::WARNING); |
| 69 | + |
| 70 | +// - Default level (DEBUG), but disallowing bubbling |
| 71 | +$handler = new ZendHQHandler('my_custom_rule', Logger::DEBUG, false); |
| 72 | + |
| 73 | +// PHP 8: |
| 74 | +// - Default level (DEBUG) and allowing bubbling: |
| 75 | +$handler = new ZendHQHandler('my_custom_rule'); |
| 76 | + |
| 77 | +// - Setting a level mask of warnings or greater only: |
| 78 | +$handler = new ZendHQHandler('my_custom_rule', level: Logger::WARNING); |
| 79 | + |
| 80 | +// - Default level (DEBUG), but disallowing bubbling |
| 81 | +$handler = new ZendHQHandler('my_custom_rule', bubble: false); |
| 82 | +``` |
| 83 | + |
| 84 | +### Formatters and Processors |
| 85 | + |
| 86 | +The `ZendHQHandler` implements each of `Monolog\Handler\ProcessableHandlerInterface` and `Monolog\Handler\FormattableHandlerInterface`. |
| 87 | +As such, you can attach processors and formatters to your handler in order to manipulate the information logged. |
| 88 | +See the [Monolog documentation on formatters and processors](http://seldaek.github.io/monolog/doc/02-handlers-formatters-processors.html) for more details. |
| 89 | + |
| 90 | +As examples: |
| 91 | + |
| 92 | +```php |
| 93 | +$handler->setFormatter(new \Monolog\Formatter\LineFormatter()); |
| 94 | +$handler->pushProcessor(new \Monolog\Processor\PsrLogMessageProcessor()); |
| 95 | +``` |
| 96 | + |
| 97 | +### Adding the handler to Monolog |
| 98 | + |
| 99 | +Monolog writes to _channels_, which are essentially just a way of partitioning different logs from each other. |
| 100 | + |
| 101 | +```php |
| 102 | +use Monolog\Logger; |
| 103 | + |
| 104 | +$logger = new Logger('channel_name'); |
| 105 | +``` |
| 106 | + |
| 107 | +From here, you need to add the handler to the logger: |
| 108 | + |
| 109 | +```php |
| 110 | +// Where $handler is the instance created via one of the examples in previous sections |
| 111 | +$logger->pushHandler($handler); |
| 112 | +``` |
| 113 | + |
| 114 | +To log, use one of the various logging methods of the `$logger` instance: |
| 115 | + |
| 116 | +```php |
| 117 | +$logger->warning('This is a warning!'); |
| 118 | +``` |
| 119 | + |
| 120 | +## Notes |
| 121 | + |
| 122 | +- The channel name is sent to ZendHQ monitoring events as the _type_; you will see this in the event drawer. |
0 commit comments