From a0b984a18de192d841a06ce50512838b4353a165 Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Fri, 19 Jun 2015 14:57:05 +0100 Subject: [PATCH] Split README into a few docs pages --- README.mdown | 241 ++--------------------- doc/{usage.md => 01-usage.md} | 88 +++++++-- doc/02-handlers-formatters-processors.md | 135 +++++++++++++ doc/03-utilities.md | 13 ++ doc/{extending.md => 04-extending.md} | 8 +- doc/sockets.md | 2 + 6 files changed, 246 insertions(+), 241 deletions(-) rename doc/{usage.md => 01-usage.md} (61%) create mode 100644 doc/02-handlers-formatters-processors.md create mode 100644 doc/03-utilities.md rename doc/{extending.md => 04-extending.md} (95%) diff --git a/README.mdown b/README.mdown index af745c8a..5b643183 100644 --- a/README.mdown +++ b/README.mdown @@ -1,5 +1,4 @@ -Monolog - Logging for PHP 5.3+ [![Build Status](https://secure.travis-ci.org/Seldaek/monolog.png)](http://travis-ci.org/Seldaek/monolog) -============================== +# 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) @@ -17,8 +16,7 @@ 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 ------------- +## Installation Install the latest version with @@ -26,8 +24,7 @@ Install the latest version with $ composer require monolog/monolog ``` -Usage ------ +## Basic Usage ```php addWarning('Foo'); $log->addError('Bar'); ``` -Core Concepts -------------- +## Documentation -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. +- [Usage Instructions](doc/01-usage.md) +- [Handlers, Formatters and Processors](doc/02-handlers-formatters-processors.md) +- [Utility classes](doc/03-utilities.md) +- [Extending Monolog](doc/04-extending.md) -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 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 -===== +## About -Requirements ------------- +### Requirements - Monolog works with PHP 5.3 or above, and is also tested to work with HHVM. -Submitting bugs and feature requests ------------------------------------- +### Submitting bugs and feature requests Bugs and feature request are tracked on [GitHub](https://github.com/Seldaek/monolog/issues) -Frameworks Integration ----------------------- +### Framework Integrations - 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. @@ -282,21 +78,18 @@ Frameworks Integration - [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. +- [Proton Micro Framework](https://github.com/alexbilbie/Proton) comes out of the box with Monolog. -Author ------- +### Author Jordi Boggiano - -
See also the list of [contributors](https://github.com/Seldaek/monolog/contributors) which participated in this project. -License -------- +### License Monolog is licensed under the MIT License - see the `LICENSE` file for details -Acknowledgements ----------------- +### 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. diff --git a/doc/usage.md b/doc/01-usage.md similarity index 61% rename from doc/usage.md rename to doc/01-usage.md index 9a9f3048..dcf0e8f4 100644 --- a/doc/usage.md +++ b/doc/01-usage.md @@ -1,22 +1,85 @@ -Using Monolog -============= +# Using Monolog -Installation ------------- +- [Installation](#installation) +- [Core Concepts](#core-concepts) +- [Log Levels](#log-levels) +- [Configuring a logger](#configuring-a-logger) +- [Adding extra data in the records](#adding-extra-data-in-the-records) +- [Leveraging channels](#leveraging-channels) +- [Customizing the log format](#customizing-the-log-format) + +## Installation Monolog is available on Packagist ([monolog/monolog](http://packagist.org/packages/monolog/monolog)) and as such installable via [Composer](http://getcomposer.org/). ```bash -php composer.phar require monolog/monolog +composer require monolog/monolog ``` If you do not use Composer, you can grab the code from GitHub, and use any PSR-0 compatible autoloader (e.g. the [Symfony2 ClassLoader component](https://github.com/symfony/ClassLoader)) to load Monolog classes. -Configuring a logger --------------------- +## 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. + +## Configuring a logger Here is a basic setup to log to a file and to firephp on the DEBUG level: @@ -53,8 +116,7 @@ you want to override other configured loggers. > configure many handlers, the [theorchard/monolog-cascade](https://github.com/theorchard/monolog-cascade) > can help you build complex logging configs via PHP arrays, yaml or json configs. -Adding extra data in the records --------------------------------- +## Adding extra data in the records Monolog provides two different ways to add extra informations along the simple textual message. @@ -97,8 +159,7 @@ Look at the [README file](https://github.com/Seldaek/monolog/blob/master/README. > Tip: processors can also be registered on a specific handler instead of the logger to apply only for this handler. -Leveraging channels -------------------- +## Leveraging channels Channels are a great way to identify to which part of the application a record is related. This is useful in big applications (and is leveraged by @@ -130,8 +191,7 @@ $securityLogger->pushHandler($stream); $securityLogger->pushHandler($firephp); ``` -Customizing log format ----------------------- +## Customizing the log format In Monolog it's easy to customize the format of the logs written into files, sockets, mails, databases and other handlers. Most of the handlers use the @@ -164,3 +224,5 @@ $securityLogger->pushHandler($stream); You may also reuse the same formatter between multiple handlers and share those handlers between multiple loggers. + +[Handlers, Formatters and Processors](02-handlers-formatters-processors.md) → diff --git a/doc/02-handlers-formatters-processors.md b/doc/02-handlers-formatters-processors.md new file mode 100644 index 00000000..d9fd154b --- /dev/null +++ b/doc/02-handlers-formatters-processors.md @@ -0,0 +1,135 @@ +# Handlers, Formatters and Processors + +- [Handlers](#handlers) +- [Formatters](#formatters) +- [Processors](#processors) +- [Third Party Packages](#third-party-packages) + +# 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](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. + +# 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. + +← [Usage](01-usage.md) | [Utility classes](03-utilities.md) → diff --git a/doc/03-utilities.md b/doc/03-utilities.md new file mode 100644 index 00000000..c62aa416 --- /dev/null +++ b/doc/03-utilities.md @@ -0,0 +1,13 @@ +# 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. + +← [Handlers, Formatters and Processors](02-handlers-formatters-processors.md) | [Extending Monolog](04-extending.md) → diff --git a/doc/extending.md b/doc/04-extending.md similarity index 95% rename from doc/extending.md rename to doc/04-extending.md index bb39ddcf..ebd9104d 100644 --- a/doc/extending.md +++ b/doc/04-extending.md @@ -1,10 +1,8 @@ -Extending Monolog -================= +# Extending Monolog Monolog is fully extensible, allowing you to adapt your logger to your needs. -Writing your own handler ------------------------- +## Writing your own handler Monolog provides many built-in handlers. But if the one you need does not exist, you can write it and use it in your logger. The only requirement is @@ -74,3 +72,5 @@ $logger->addInfo('My logger is now ready'); The `Monolog\Handler\AbstractProcessingHandler` class provides most of the logic needed for the handler, including the use of processors and the formatting of the record (which is why we use ``$record['formatted']`` instead of ``$record['message']``). + +← [Utility classes](03-utilities.md) diff --git a/doc/sockets.md b/doc/sockets.md index fad30a9f..ea9cf0ea 100644 --- a/doc/sockets.md +++ b/doc/sockets.md @@ -7,6 +7,8 @@ or [pfsockopen](http://php.net/pfsockopen). Persistent sockets are mainly useful in web environments where you gain some performance not closing/opening the connections between requests. +You can use a `unix://` prefix to access unix sockets and `udp://` to open UDP sockets instead of the default TCP. + Basic Example -------------