diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/01-usage.md | 8 | ||||
| -rw-r--r-- | doc/02-handlers-formatters-processors.md | 146 | ||||
| -rw-r--r-- | doc/04-extending.md | 9 | ||||
| -rw-r--r-- | doc/message-structure.md | 18 | ||||
| -rw-r--r-- | doc/sockets.md | 2 |
5 files changed, 108 insertions, 75 deletions
diff --git a/doc/01-usage.md b/doc/01-usage.md index 8e2551f..ec9bbbb 100644 --- a/doc/01-usage.md +++ b/doc/01-usage.md @@ -24,7 +24,7 @@ to load Monolog classes. ## 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 +you add a [record](message-structure.md) 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. @@ -97,7 +97,7 @@ $logger->pushHandler(new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG)); $logger->pushHandler(new FirePHPHandler()); // You can now use your logger -$logger->addInfo('My logger is now ready'); +$logger->info('My logger is now ready'); ``` Let's explain it. The first step is to create the logger instance which will @@ -118,7 +118,7 @@ you want to override other configured loggers. ## Adding extra data in the records -Monolog provides two different ways to add extra informations along the simple +Monolog provides two different ways to add extra information along the simple textual message. ### Using the logging context @@ -129,7 +129,7 @@ record: ```php <?php -$logger->addInfo('Adding a new user', array('username' => 'Seldaek')); +$logger->info('Adding a new user', array('username' => 'Seldaek')); ``` Simple handlers (like the StreamHandler for instance) will simply format diff --git a/doc/02-handlers-formatters-processors.md b/doc/02-handlers-formatters-processors.md index bea968a..9987908 100644 --- a/doc/02-handlers-formatters-processors.md +++ b/doc/02-handlers-formatters-processors.md @@ -15,71 +15,75 @@ ### 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. +- [_StreamHandler_](../src/Monolog/Handler/StreamHandler.php): Logs records into any PHP stream, use this for log files. +- [_RotatingFileHandler_](../src/Monolog/Handler/RotatingFileHandler.php): 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 +- [_SyslogHandler_](../src/Monolog/Handler/SyslogHandler.php): Logs records to the syslog. +- [_ErrorLogHandler_](../src/Monolog/Handler/ErrorLogHandler.php): Logs records to PHP's [`error_log()`](http://docs.php.net/manual/en/function.error-log.php) function. +- [_ProcessHandler_](../src/Monolog/Handler/ProcessHandler.php): Logs records to the [STDIN](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_.28stdin.29) of any process, specified by a command. ### Send alerts and emails -- _NativeMailerHandler_: Sends emails using PHP's +- [_NativeMailerHandler_](../src/Monolog/Handler/NativeMailerHandler.php): 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 using the Slack API. -- _SlackbotHandler_: Logs records to a [Slack](https://www.slack.com/) account using the Slackbot incoming hook. -- _SlackWebhookHandler_: Logs records to a [Slack](https://www.slack.com/) account using Slack Webhooks. -- _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. -- _IFTTTHandler_: Notifies an [IFTTT](https://ifttt.com/maker) trigger with the log channel, level name and message. +- [_SwiftMailerHandler_](../src/Monolog/Handler/SwiftMailerHandler.php): Sends emails using a [`Swift_Mailer`](http://swiftmailer.org/) instance. +- [_PushoverHandler_](../src/Monolog/Handler/PushoverHandler.php): Sends mobile notifications via the [Pushover](https://www.pushover.net/) API. +- [_HipChatHandler_](../src/Monolog/Handler/HipChatHandler.php): Logs records to a [HipChat](http://hipchat.com) chat room using its API. +- [_FlowdockHandler_](../src/Monolog/Handler/FlowdockHandler.php): Logs records to a [Flowdock](https://www.flowdock.com/) account. +- [_SlackbotHandler_](../src/Monolog/Handler/SlackbotHandler.php): Logs records to a [Slack](https://www.slack.com/) account using the Slackbot incoming hook. +- [_SlackWebhookHandler_](../src/Monolog/Handler/SlackWebhookHandler.php): Logs records to a [Slack](https://www.slack.com/) account using Slack Webhooks. +- [_SlackHandler_](../src/Monolog/Handler/SlackHandler.php): Logs records to a [Slack](https://www.slack.com/) account using the Slack API (complex setup). +- [_SendGridHandler_](../src/Monolog/Handler/SendGridHandler.php): Sends emails via the SendGrid API. +- [_MandrillHandler_](../src/Monolog/Handler/MandrillHandler.php): Sends emails via the Mandrill API using a [`Swift_Message`](http://swiftmailer.org/) instance. +- [_FleepHookHandler_](../src/Monolog/Handler/FleepHookHandler.php): Logs records to a [Fleep](https://fleep.io/) conversation using Webhooks. +- [_IFTTTHandler_](../src/Monolog/Handler/IFTTTHandler.php): Notifies an [IFTTT](https://ifttt.com/maker) trigger with the log channel, level name and message. ### Log specific servers and networked logging -- _SocketHandler_: Logs records to [sockets](http://php.net/fsockopen), use this +- [_SocketHandler_](../src/Monolog/Handler/SocketHandler.php): Logs records to [sockets](http://php.net/fsockopen), use this for UNIX and TCP sockets. See an [example](sockets.md). -- _AmqpHandler_: Logs records to an [amqp](http://www.amqp.org/) compatible +- [_AmqpHandler_](../src/Monolog/Handler/AmqpHandler.php): 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 +- [_GelfHandler_](../src/Monolog/Handler/GelfHandler.php): Logs records to a [Graylog2](http://www.graylog2.org) server. +- [_CubeHandler_](../src/Monolog/Handler/CubeHandler.php): Logs records to a [Cube](http://square.github.com/cube/) server. +- [_RavenHandler_](../src/Monolog/Handler/RavenHandler.php): 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. +- [_ZendMonitorHandler_](../src/Monolog/Handler/ZendMonitorHandler.php): Logs records to the Zend Monitor present in Zend Server. +- [_NewRelicHandler_](../src/Monolog/Handler/NewRelicHandler.php): Logs records to a [NewRelic](http://newrelic.com/) application. +- [_LogglyHandler_](../src/Monolog/Handler/LogglyHandler.php): Logs records to a [Loggly](http://www.loggly.com/) account. +- [_RollbarHandler_](../src/Monolog/Handler/RollbarHandler.php): Logs records to a [Rollbar](https://rollbar.com/) account. +- [_SyslogUdpHandler_](../src/Monolog/Handler/SyslogUdpHandler.php): Logs records to a remote [Syslogd](http://www.rsyslog.com/) server. +- [_LogEntriesHandler_](../src/Monolog/Handler/LogEntriesHandler.php): Logs records to a [LogEntries](http://logentries.com/) account. +- [_LogmaticHandler_](../src/Monolog/Handler/LogmaticHandler.php): Logs records to a [Logmatic](http://logmatic.io/) account. +- [_SqsHandler_](../src/Monolog/Handler/SqsHandler.php): Logs records to an [AWS SQS](http://docs.aws.amazon.com/aws-sdk-php/v2/guide/service-sqs.html) queue. ### Logging in development -- _FirePHPHandler_: Handler for [FirePHP](http://www.firephp.org/), providing +- [_FirePHPHandler_](../src/Monolog/Handler/FirePHPHandler.php): 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 +- [_ChromePHPHandler_](../src/Monolog/Handler/ChromePHPHandler.php): Handler for [ChromePHP](http://www.chromephp.com/), providing inline `console` messages within Chrome. -- _BrowserConsoleHandler_: Handler to send logs to browser's Javascript `console` with +- [_BrowserConsoleHandler_](../src/Monolog/Handler/BrowserConsoleHandler.php): 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 +- [_PHPConsoleHandler_](../src/Monolog/Handler/PHPConsoleHandler.php): 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 +- [_RedisHandler_](../src/Monolog/Handler/RedisHandler.php): Logs records to a [redis](http://redis.io) server. +- [_MongoDBHandler_](../src/Monolog/Handler/MongoDBHandler.php): 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). +- [_CouchDBHandler_](../src/Monolog/Handler/CouchDBHandler.php): Logs records to a CouchDB server. +- [_DoctrineCouchDBHandler_](../src/Monolog/Handler/DoctrineCouchDBHandler.php): Logs records to a CouchDB server via the Doctrine CouchDB ODM. +- [_ElasticSearchHandler_](../src/Monolog/Handler/ElasticSearchHandler.php): Logs records to an Elastic Search server. +- [_DynamoDbHandler_](../src/Monolog/Handler/DynamoDbHandler.php): 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 +- [_FingersCrossedHandler_](../src/Monolog/Handler/FingersCrossedHandler.php): 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 @@ -87,7 +91,7 @@ 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. -- _DeduplicationHandler_: Useful if you are sending notifications or emails +- [_DeduplicationHandler_](../src/Monolog/Handler/DeduplicationHandler.php): Useful if you are sending notifications or emails when critical errors occur. It takes a logger as parameter and will accumulate log records of all levels until the end of the request (or `flush()` is called). At that point it delivers all records to the handler @@ -97,56 +101,60 @@ database is unreachable for example all your requests will fail and that can result in a lot of notifications being sent. Adding this handler reduces the amount of notifications to a manageable level. -- _WhatFailureGroupHandler_: This handler extends the _GroupHandler_ ignoring +- [_WhatFailureGroupHandler_](../src/Monolog/Handler/WhatFailureGroupHandler.php): 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 +- [_BufferHandler_](../src/Monolog/Handler/BufferHandler.php): 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 +- [_GroupHandler_](../src/Monolog/Handler/GroupHandler.php): 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 +- [_FilterHandler_](../src/Monolog/Handler/FilterHandler.php): This handler only lets records of the given levels through to the wrapped handler. -- _SamplingHandler_: Wraps around another handler and lets you sample records +- [_SamplingHandler_](../src/Monolog/Handler/SamplingHandler.php): 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 +- [_NoopHandler_](../src/Monolog/Handler/NoopHandler.php): This handler handles anything by doing nothing. It does not stop + processing the rest of the stack. This can be used for testing, or to disable a handler when overriding a configuration. +- [_NullHandler_](../src/Monolog/Handler/NullHandler.php): 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 +- [_PsrHandler_](../src/Monolog/Handler/PsrHandler.php): Can be used to forward log records to an existing PSR-3 logger +- [_TestHandler_](../src/Monolog/Handler/TestHandler.php): Used for testing, it records everything that is sent to it and has accessors to read out the information. -- _HandlerWrapper_: A simple handler wrapper you can inherit from to create +- [_HandlerWrapper_](../src/Monolog/Handler/HandlerWrapper.php): A simple handler wrapper you can inherit from to create your own wrappers easily. ## 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. +- [_LineFormatter_](../src/Monolog/Formatter/LineFormatter.php): Formats a log record into a one-line string. +- [_HtmlFormatter_](../src/Monolog/Formatter/HtmlFormatter.php): Used to format log records into a human readable html table, mainly suitable for emails. +- [_NormalizerFormatter_](../src/Monolog/Formatter/NormalizerFormatter.php): Normalizes objects/resources down to strings so a record can easily be serialized/encoded. +- [_ScalarFormatter_](../src/Monolog/Formatter/ScalarFormatter.php): Used to format log records into an associative array of scalar values. +- [_JsonFormatter_](../src/Monolog/Formatter/JsonFormatter.php): Encodes a log record into json. +- [_WildfireFormatter_](../src/Monolog/Formatter/WildfireFormatter.php): Used to format log records into the Wildfire/FirePHP protocol, only useful for the FirePHPHandler. +- [_ChromePHPFormatter_](../src/Monolog/Formatter/ChromePHPFormatter.php): Used to format log records into the ChromePHP format, only useful for the ChromePHPHandler. +- [_GelfMessageFormatter_](../src/Monolog/Formatter/GelfMessageFormatter.php): Used to format log records into Gelf message instances, only useful for the GelfHandler. +- [_LogstashFormatter_](../src/Monolog/Formatter/LogstashFormatter.php): 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_](../src/Monolog/Formatter/ElasticaFormatter.php): Used to format log records into an Elastica\Document object, only useful for the ElasticSearchHandler. +- [_LogglyFormatter_](../src/Monolog/Formatter/LogglyFormatter.php): Used to format log records into Loggly messages, only useful for the LogglyHandler. +- [_FlowdockFormatter_](../src/Monolog/Formatter/FlowdockFormatter.php): Used to format log records into Flowdock messages, only useful for the FlowdockHandler. +- [_MongoDBFormatter_](../src/Monolog/Formatter/MongoDBFormatter.php): Converts \DateTime instances to \MongoDate and objects recursively to arrays, only useful with the MongoDBHandler. +- [_LogmaticFormatter_](../src/Monolog/Formatter/LogmaticFormatter.php): User to format log records to [Logmatic](http://logmatic.io/) messages, only useful for the LogmaticHandler. ## Processors -- _PsrLogMessageProcessor_: Processes a log record's message according to PSR-3 rules, replacing `{foo}` with the value from `$context['foo']`. -- _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. +- [_PsrLogMessageProcessor_](../src/Monolog/Processor/PsrLogMessageProcessor.php): Processes a log record's message according to PSR-3 rules, replacing `{foo}` with the value from `$context['foo']`. +- [_IntrospectionProcessor_](../src/Monolog/Processor/IntrospectionProcessor.php): Adds the line/file/class/method from which the log call originated. +- [_WebProcessor_](../src/Monolog/Processor/WebProcessor.php): Adds the current request URI, request method and client IP to a log record. +- [_MemoryUsageProcessor_](../src/Monolog/Processor/MemoryUsageProcessor.php): Adds the current memory usage to a log record. +- [_MemoryPeakUsageProcessor_](../src/Monolog/Processor/MemoryPeakUsageProcessor.php): Adds the peak memory usage to a log record. +- [_ProcessIdProcessor_](../src/Monolog/Processor/ProcessIdProcessor.php): Adds the process id to a log record. +- [_UidProcessor_](../src/Monolog/Processor/UidProcessor.php): Adds a unique identifier to a log record. +- [_GitProcessor_](../src/Monolog/Processor/GitProcessor.php): Adds the current git branch and commit to a log record. +- [_MercurialProcessor_](../src/Monolog/Processor/MercurialProcessor.php): Adds the current hg branch and commit to a log record. +- [_TagProcessor_](../src/Monolog/Processor/TagProcessor.php): Adds an array of predefined tags to a log record. ## Third Party Packages diff --git a/doc/04-extending.md b/doc/04-extending.md index ebd9104..ffb0700 100644 --- a/doc/04-extending.md +++ b/doc/04-extending.md @@ -2,6 +2,13 @@ Monolog is fully extensible, allowing you to adapt your logger to your needs. +## Understanding log records + +See [the page about log records](message-structure.md) to learn what makes up +a log record before going further. This is essential to understand as all +Handlers/Formatters/Processors need to deal with log records in one way or +another. + ## Writing your own handler Monolog provides many built-in handlers. But if the one you need does not @@ -66,7 +73,7 @@ You can now use this handler in your logger: $logger->pushHandler(new PDOHandler(new PDO('sqlite:logs.sqlite'))); // You can now use your logger -$logger->addInfo('My logger is now ready'); +$logger->info('My logger is now ready'); ``` The `Monolog\Handler\AbstractProcessingHandler` class provides most of the diff --git a/doc/message-structure.md b/doc/message-structure.md new file mode 100644 index 0000000..093a10c --- /dev/null +++ b/doc/message-structure.md @@ -0,0 +1,18 @@ +# Log message structure + +Within monolog log messages are passed around as arrays, for example to processors or handlers. +The table below describes which keys are always available for every log message. + +key | type | description +-----------|---------------------------|------------------------------------------------------------------------------- +message | string | The log message. When the `PsrLogMessageProcessor` is used this string may contain placeholders that will be replaced by variables from the context, e.g., "User %username% logged in" with `['username' => 'John']` as context will be written as "User John logged in". +level | int | Severity of the log message. See log levels described in [01-usage.md](01-usage.md). +level_name | string | String representation of log level. +context | array | Arbitrary data passed with the construction of the message. For example the username of the current user or their IP address. +channel | string | The channel this message was logged to. This is the name that was passed when the logger was created with `new Logger($channel)`. +datetime | Monolog\DateTimeImmutable | Date and time when the message was logged. Class extends `\DateTimeImmutable`. +extra | array | A placeholder array where processors can put additional data. Always available, but empty if there are no processors registered. + +At first glance `context` and `extra` look very similar, and they are in the sense that they both carry arbitrary data that is related to the log message somehow. +The main difference is that `context` can be supplied in user land (it is the 3rd parameter to `Logger::addRecord()`) whereas `extra` is internal only and can be filled by processors. +The reason processors write to `extra` and not to `context` is to prevent overriding any user provided data in `context`. diff --git a/doc/sockets.md b/doc/sockets.md index ea9cf0e..c1190c2 100644 --- a/doc/sockets.md +++ b/doc/sockets.md @@ -29,7 +29,7 @@ $handler->setPersistent(true); $logger->pushHandler($handler, Logger::DEBUG); // You can now use your logger -$logger->addInfo('My logger is now ready'); +$logger->info('My logger is now ready'); ``` |