Monolog - Logging for PHP 5.3+ [![Build Status](https://secure.travis-ci.org/Seldaek/monolog.png)](http://travis-ci.org/Seldaek/monolog) ============================== [![Total Downloads](https://poser.pugx.org/monolog/monolog/downloads.png)](https://packagist.org/packages/monolog/monolog) [![Latest Stable Version](https://poser.pugx.org/monolog/monolog/v/stable.png)](https://packagist.org/packages/monolog/monolog) [![Reference Status](https://www.versioneye.com/php/monolog:monolog/reference_badge.svg)](https://www.versioneye.com/php/monolog:monolog/references) Monolog sends your logs to files, sockets, inboxes, databases and various web services. See the complete list of handlers below. Special handlers allow you to build advanced logging strategies. This library implements the [PSR-3](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md) interface that you can type-hint against in your own libraries to keep a maximum of interoperability. You can also use it in your applications to make sure you can always use another compatible logger at a later time. As of 1.11.0 Monolog public APIs will also accept PSR-3 log levels. Internally Monolog still uses its own level scheme since it predates PSR-3. Installation ------------ Install the latest version with ```bash $ composer require monolog/monolog ``` Usage ----- ```php pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING)); // add records to the log $log->addWarning('Foo'); $log->addError('Bar'); ``` Core Concepts ------------- Every `Logger` instance has a channel (name) and a stack of handlers. Whenever you add a record to the logger, it traverses the handler stack. Each handler decides whether it fully handled the record, and if so, the propagation of the record ends there. This allows for flexible logging setups, for example having a `StreamHandler` at the bottom of the stack that will log anything to disk, and on top of that add a `MailHandler` that will send emails only when an error message is logged. Handlers also have a `$bubble` property which defines whether they block the record or not if they handled it. In this example, setting the `MailHandler`'s `$bubble` argument to false means that records handled by the `MailHandler` will not propagate to the `StreamHandler` anymore. You can create many `Logger`s, each defining a channel (e.g.: db, request, router, ..) and each of them combining various handlers, which can be shared or not. The channel is reflected in the logs and allows you to easily see or filter records. Each Handler also has a Formatter, a default one with settings that make sense will be created if you don't set one. The formatters normalize and format incoming records so that they can be used by the handlers to output useful information. Custom severity levels are not available. Only the eight [RFC 5424](http://tools.ietf.org/html/rfc5424) levels (debug, info, notice, warning, error, critical, alert, emergency) are present for basic filtering purposes, but for sorting and other use cases that would require flexibility, you should add Processors to the Logger that can add extra information (tags, user ip, ..) to the records before they are handled. Log Levels ---------- Monolog supports the logging levels described by [RFC 5424](http://tools.ietf.org/html/rfc5424). - **DEBUG** (100): Detailed debug information. - **INFO** (200): Interesting events. Examples: User logs in, SQL logs. - **NOTICE** (250): Normal but significant events. - **WARNING** (300): Exceptional occurrences that are not errors. Examples: Use of deprecated APIs, poor use of an API, undesirable things that are not necessarily wrong. - **ERROR** (400): Runtime errors that do not require immediate action but should typically be logged and monitored. - **CRITICAL** (500): Critical conditions. Example: Application component unavailable, unexpected exception. - **ALERT** (550): Action must be taken immediately. Example: Entire website down, database unavailable, etc. This should trigger the SMS alerts and wake you up. - **EMERGENCY** (600): Emergency: system is unusable. Docs ==== **See the `doc` directory for more detailed documentation. The following is only a list of all parts that come with Monolog.** Handlers -------- ### Log to files and syslog - _StreamHandler_: Logs records into any PHP stream, use this for log files. - _RotatingFileHandler_: Logs records to a file and creates one logfile per day. It will also delete files older than `$maxFiles`. You should use [logrotate](http://linuxcommand.org/man_pages/logrotate8.html) for high profile setups though, this is just meant as a quick and dirty solution. - _SyslogHandler_: Logs records to the syslog. - _ErrorLogHandler_: Logs records to PHP's [`error_log()`](http://docs.php.net/manual/en/function.error-log.php) function. ### Send alerts and emails - _NativeMailerHandler_: Sends emails using PHP's [`mail()`](http://php.net/manual/en/function.mail.php) function. - _SwiftMailerHandler_: Sends emails using a [`Swift_Mailer`](http://swiftmailer.org/) instance. - _PushoverHandler_: Sends mobile notifications via the [Pushover](https://www.pushover.net/) API. - _HipChatHandler_: Logs records to a [HipChat](http://hipchat.com) chat room using its API. - _FlowdockHandler_: Logs records to a [Flowdock](https://www.flowdock.com/) account. - _SlackHandler_: Logs records to a [Slack](https://www.slack.com/) account. - _MandrillHandler_: Sends emails via the Mandrill API using a [`Swift_Message`](http://swiftmailer.org/) instance. - _FleepHookHandler_: Logs records to a [Fleep](https://fleep.io/) conversation using Webhooks. ### Log specific servers and networked logging - _SocketHandler_: Logs records to [sockets](http://php.net/fsockopen), use this for UNIX and TCP sockets. See an [example](https://github.com/Seldaek/monolog/blob/master/doc/sockets.md). - _AmqpHandler_: Logs records to an [amqp](http://www.amqp.org/) compatible server. Requires the [php-amqp](http://pecl.php.net/package/amqp) extension (1.0+). - _GelfHandler_: Logs records to a [Graylog2](http://www.graylog2.org) server. - _CubeHandler_: Logs records to a [Cube](http://square.github.com/cube/) server. - _RavenHandler_: Logs records to a [Sentry](http://getsentry.com/) server using [raven](https://packagist.org/packages/raven/raven). - _ZendMonitorHandler_: Logs records to the Zend Monitor present in Zend Server. - _NewRelicHandler_: Logs records to a [NewRelic](http://newrelic.com/) application. - _LogglyHandler_: Logs records to a [Loggly](http://www.loggly.com/) account. - _RollbarHandler_: Logs records to a [Rollbar](https://rollbar.com/) account. - _SyslogUdpHandler_: Logs records to a remote [Syslogd](http://www.rsyslog.com/) server. - _LogEntriesHandler_: Logs records to a [LogEntries](http://logentries.com/) account. ### Logging in development - _FirePHPHandler_: Handler for [FirePHP](http://www.firephp.org/), providing inline `console` messages within [FireBug](http://getfirebug.com/). - _ChromePHPHandler_: Handler for [ChromePHP](http://www.chromephp.com/), providing inline `console` messages within Chrome. - _BrowserConsoleHandler_: Handler to send logs to browser's Javascript `console` with no browser extension required. Most browsers supporting `console` API are supported. - _PHPConsoleHandler_: Handler for [PHP Console](https://chrome.google.com/webstore/detail/php-console/nfhmhhlpfleoednkpnnnkolmclajemef), providing inline `console` and notification popup messages within Chrome. ### Log to databases - _RedisHandler_: Logs records to a [redis](http://redis.io) server. - _MongoDBHandler_: Handler to write records in MongoDB via a [Mongo](http://pecl.php.net/package/mongo) extension connection. - _CouchDBHandler_: Logs records to a CouchDB server. - _DoctrineCouchDBHandler_: Logs records to a CouchDB server via the Doctrine CouchDB ODM. - _ElasticSearchHandler_: Logs records to an Elastic Search server. - _DynamoDbHandler_: Logs records to a DynamoDB table with the [AWS SDK](https://github.com/aws/aws-sdk-php). ### Wrappers / Special Handlers - _FingersCrossedHandler_: A very interesting wrapper. It takes a logger as parameter and will accumulate log records of all levels until a record exceeds the defined severity level. At which point it delivers all records, including those of lower severity, to the handler it wraps. This means that until an error actually happens you will not see anything in your logs, but when it happens you will have the full information, including debug and info records. This provides you with all the information you need, but only when you need it. - _WhatFailureGroupHandler_: This handler extends the _GroupHandler_ ignoring exceptions raised by each child handler. This allows you to ignore issues where a remote tcp connection may have died but you do not want your entire application to crash and may wish to continue to log to other handlers. - _BufferHandler_: This handler will buffer all the log records it receives until `close()` is called at which point it will call `handleBatch()` on the handler it wraps with all the log messages at once. This is very useful to send an email with all records at once for example instead of having one mail for every log record. - _GroupHandler_: This handler groups other handlers. Every record received is sent to all the handlers it is configured with. - _FilterHandler_: This handler only lets records of the given levels through to the wrapped handler. - _SamplingHandler_: Wraps around another handler and lets you sample records if you only want to store some of them. - _NullHandler_: Any record it can handle will be thrown away. This can be used to put on top of an existing handler stack to disable it temporarily. - _PsrHandler_: Can be used to forward log records to an existing PSR-3 logger - _TestHandler_: Used for testing, it records everything that is sent to it and has accessors to read out the information. Formatters ---------- - _LineFormatter_: Formats a log record into a one-line string. - _HtmlFormatter_: Used to format log records into a human readable html table, mainly suitable for emails. - _NormalizerFormatter_: Normalizes objects/resources down to strings so a record can easily be serialized/encoded. - _ScalarFormatter_: Used to format log records into an associative array of scalar values. - _JsonFormatter_: Encodes a log record into json. - _WildfireFormatter_: Used to format log records into the Wildfire/FirePHP protocol, only useful for the FirePHPHandler. - _ChromePHPFormatter_: Used to format log records into the ChromePHP format, only useful for the ChromePHPHandler. - _GelfMessageFormatter_: Used to format log records into Gelf message instances, only useful for the GelfHandler. - _LogstashFormatter_: Used to format log records into [logstash](http://logstash.net/) event json, useful for any handler listed under inputs [here](http://logstash.net/docs/latest). - _ElasticaFormatter_: Used to format log records into an Elastica\Document object, only useful for the ElasticSearchHandler. - _LogglyFormatter_: Used to format log records into Loggly messages, only useful for the LogglyHandler. - _FlowdockFormatter_: Used to format log records into Flowdock messages, only useful for the FlowdockHandler. - _MongoDBFormatter_: Converts \DateTime instances to \MongoDate and objects recursively to arrays, only useful with the MongoDBHandler. Processors ---------- - _IntrospectionProcessor_: Adds the line/file/class/method from which the log call originated. - _WebProcessor_: Adds the current request URI, request method and client IP to a log record. - _MemoryUsageProcessor_: Adds the current memory usage to a log record. - _MemoryPeakUsageProcessor_: Adds the peak memory usage to a log record. - _ProcessIdProcessor_: Adds the process id to a log record. - _UidProcessor_: Adds a unique identifier to a log record. - _GitProcessor_: Adds the current git branch and commit to a log record. - _TagProcessor_: Adds an array of predefined tags to a log record. Utilities --------- - _Registry_: The `Monolog\Registry` class lets you configure global loggers that you can then statically access from anywhere. It is not really a best practice but can help in some older codebases or for ease of use. - _ErrorHandler_: The `Monolog\ErrorHandler` class allows you to easily register a Logger instance as an exception handler, error handler or fatal error handler. - _ErrorLevelActivationStrategy_: Activates a FingersCrossedHandler when a certain log level is reached. - _ChannelLevelActivationStrategy_: Activates a FingersCrossedHandler when a certain log level is reached, depending on which channel received the log record. Third Party Packages -------------------- Third party handlers, formatters and processors are [listed in the wiki](https://github.com/Seldaek/monolog/wiki/Third-Party-Packages). You can also add your own there if you publish one. About ===== Requirements ------------ - Monolog works with PHP 5.3 or above, and is also tested to work with HHVM. Submitting bugs and feature requests ------------------------------------ Bugs and feature request are tracked on [GitHub](https://github.com/Seldaek/monolog/issues) Frameworks Integration ---------------------- - Frameworks and libraries using [PSR-3](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md) can be used very easily with Monolog since it implements the interface. - [Symfony2](http://symfony.com) comes out of the box with Monolog. - [Silex](http://silex.sensiolabs.org/) comes out of the box with Monolog. - [Laravel 4 & 5](http://laravel.com/) come out of the box with Monolog. - [Lumen](http://lumen.laravel.com/) comes out of the box with Monolog. - [PPI](http://www.ppi.io/) comes out of the box with Monolog. - [CakePHP](http://cakephp.org/) is usable with Monolog via the [cakephp-monolog](https://github.com/jadb/cakephp-monolog) plugin. - [Slim](http://www.slimframework.com/) is usable with Monolog via the [Slim-Monolog](https://github.com/Flynsarmy/Slim-Monolog) log writer. - [XOOPS 2.6](http://xoops.org/) comes out of the box with Monolog. - [Aura.Web_Project](https://github.com/auraphp/Aura.Web_Project) comes out of the box with Monolog. - [Nette Framework](http://nette.org/en/) can be used with Monolog via [Kdyby/Monolog](https://github.com/Kdyby/Monolog) extension. - [Proton Micro Framework](https://github.com/alexbilbie/Proton) comes out of the box with Monolog. Author ------ Jordi Boggiano - -
See also the list of [contributors](https://github.com/Seldaek/monolog/contributors) which participated in this project. License ------- Monolog is licensed under the MIT License - see the `LICENSE` file for details Acknowledgements ---------------- This library is heavily inspired by Python's [Logbook](http://packages.python.org/Logbook/) library, although most concepts have been adjusted to fit to the PHP world.