Skip to content
Newer
Older
100644 189 lines (145 sloc) 7.89 KB
2ff85ba @Seldaek Added README file
authored
1 Monolog - Logging for PHP 5.3
2 =============================
3
e06590f @Seldaek Edit travis URL
authored
4 [![Build Status](https://secure.travis-ci.org/Seldaek/monolog.png)](http://travis-ci.org/Seldaek/monolog)
9321403 @pborreli [CI] Adding travis-ci status icon
pborreli authored
5
2ff85ba @Seldaek Added README file
authored
6 Usage
7 -----
8
acd05ec @msabramo Add GitHub PHP syntax highlighting to example
msabramo authored
9 ```php
10 <?php
2ff85ba @Seldaek Added README file
authored
11
acd05ec @msabramo Add GitHub PHP syntax highlighting to example
msabramo authored
12 use Monolog\Logger;
13 use Monolog\Handler\StreamHandler;
2ff85ba @Seldaek Added README file
authored
14
acd05ec @msabramo Add GitHub PHP syntax highlighting to example
msabramo authored
15 // create a log channel
16 $log = new Logger('name');
17 $log->pushHandler(new StreamHandler('path/to/your.log', Logger::WARNING));
18
19 // add records to the log
20 $log->addWarning('Foo');
21 $log->addError('Bar');
22 ```
2ff85ba @Seldaek Added README file
authored
23
8d27400 @Seldaek Updated README
authored
24 Core Concepts
25 -------------
26
cac3860 @msabramo README.mdown tweaks
msabramo authored
27 Every `Logger` instance has a channel (name) and a stack of handlers. Whenever
3b910c3 @Seldaek Rewrap README
authored
28 you add a record to the logger, it traverses the handler stack. Each handler
29 decides whether it handled fully the record, and if so, the propagation of the
30 record ends there.
31
cac3860 @msabramo README.mdown tweaks
msabramo authored
32 This allow for flexible logging setups, for example having a `StreamHandler` at
3b910c3 @Seldaek Rewrap README
authored
33 the bottom of the stack that will log anything to disk, and on top of that add
cac3860 @msabramo README.mdown tweaks
msabramo authored
34 a `MailHandler` that will send emails only when an error message is logged.
4f53e25 @Seldaek Fix language
authored
35 Handlers also have a `$bubble` property which defines whether they block the
cac3860 @msabramo README.mdown tweaks
msabramo authored
36 record or not if they handled it. In this example, setting the `MailHandler`'s
37 `$bubble` argument to true means that all records will propagate to the
38 `StreamHandler`, even the errors that are handled by the `MailHandler`.
3b910c3 @Seldaek Rewrap README
authored
39
cac3860 @msabramo README.mdown tweaks
msabramo authored
40 You can create many `Logger`s, each defining a channel (e.g.: db, request,
3b910c3 @Seldaek Rewrap README
authored
41 router, ..) and each of them combining various handlers, which can be shared
42 or not. The channel is reflected in the logs and allows you to easily see or
43 filter records.
44
45 Each Handler also has a Formatter, a default one with settings that make sense
46 will be created if you don't set one. The formatters normalize and format
47 incoming records so that they can be used by the handlers to output useful
48 information.
49
c8ca427 @Seldaek Cosmetic fixes
authored
50 Custom severity levels are not available. Only the eight
51 [RFC 5424](http://tools.ietf.org/html/rfc5424) levels (debug, info, notice,
52 warning, error, critical, alert, emergency) are present for basic filtering
53 purposes, but for sorting and other use cases that would require
54 flexibility, you should add Processors to the Logger that can add extra
07aac12 @FGM Implement the 8 RFC3164 severity levels instead of just 6.
FGM authored
55 information (tags, user ip, ..) to the records before they are handled.
8d27400 @Seldaek Updated README
authored
56
18598c0 @Seldaek Add log level docs, refs #69
authored
57 Log Levels
58 ----------
59
c8ca427 @Seldaek Cosmetic fixes
authored
60 Monolog supports all 8 logging levels defined in
61 [RFC 5424](http://tools.ietf.org/html/rfc5424), but unless you specifically
62 need syslog compatibility, it is advised to only use DEBUG, INFO, WARNING,
63 ERROR, CRITICAL, ALERT.
18598c0 @Seldaek Add log level docs, refs #69
authored
64
65 - **DEBUG** (100): Detailed debug information.
66
67 - **INFO** (200): Interesting events. Examples: User logs in, SQL logs.
68
c8ca427 @Seldaek Cosmetic fixes
authored
69 - NOTICE (250): Normal but significant events.
07aac12 @FGM Implement the 8 RFC3164 severity levels instead of just 6.
FGM authored
70
18598c0 @Seldaek Add log level docs, refs #69
authored
71 - **WARNING** (300): Exceptional occurrences that are not errors. Examples:
72 Use of deprecated APIs, poor use of an API, undesirable things that are not
73 necessarily wrong.
74
75 - **ERROR** (400): Runtime errors that do not require immediate action but
76 should typically be logged and monitored.
77
78 - **CRITICAL** (500): Critical conditions. Example: Application component
79 unavailable, unexpected exception.
80
81 - **ALERT** (550): Action must be taken immediately. Example: Entire website
82 down, database unavailable, etc. This should trigger the SMS alerts and wake
83 you up.
84
c8ca427 @Seldaek Cosmetic fixes
authored
85 - EMERGENCY (600): Emergency: system is unusable.
07aac12 @FGM Implement the 8 RFC3164 severity levels instead of just 6.
FGM authored
86
0ce2cb2 @Seldaek Updated README
authored
87 Docs
88 ====
89
c8ca427 @Seldaek Cosmetic fixes
authored
90 **See the `doc` directory for more detailed documentation.
cac3860 @msabramo README.mdown tweaks
msabramo authored
91 The following is only a list of all parts that come with Monolog.**
cf06541 @Seldaek Adjusments to docs/readme
authored
92
580df22 @Seldaek Updated README to document all existing handlers
authored
93 Handlers
94 --------
8d27400 @Seldaek Updated README
authored
95
cac3860 @msabramo README.mdown tweaks
msabramo authored
96 - _StreamHandler_: Logs records into any PHP stream, use this for log files.
3b910c3 @Seldaek Rewrap README
authored
97 - _RotatingFileHandler_: Logs records to a file and creates one logfile per day.
cac3860 @msabramo README.mdown tweaks
msabramo authored
98 It will also delete files older than `$maxFiles`. You should use
3b910c3 @Seldaek Rewrap README
authored
99 [logrotate](http://linuxcommand.org/man_pages/logrotate8.html) for high profile
100 setups though, this is just meant as a quick and dirty solution.
101 - _FirePHPHandler_: Handler for [FirePHP](http://www.firephp.org/), providing
102 inline `console` messages within [FireBug](http://getfirebug.com/).
103 - _ChromePHPHandler_: Handler for [ChromePHP](http://www.chromephp.com/), providing
104 inline `console` messages within Chrome.
105 - _MongoDBHandler_: Handler to write records in MongoDB via a
106 [Mongo](http://pecl.php.net/package/mongo) extension connection.
c8ca427 @Seldaek Cosmetic fixes
authored
107 - _NativeMailHandler_: Sends emails using PHP's
cac3860 @msabramo README.mdown tweaks
msabramo authored
108 [`mail()`](http://php.net/manual/en/function.mail.php) function.
89b5a3c @Seldaek Cosmetic fixes
authored
109 - _SwiftMailerHandler_: Sends emails using a [`Swift_Mailer`](http://swiftmailer.org/) instance.
580df22 @Seldaek Updated README to document all existing handlers
authored
110 - _SyslogHandler_: Logs records to the syslog.
4b2c47d @Seldaek Update README/CHANGELOG
authored
111 - _GelfHandler_: Logs records to a [Graylog2](http://www.graylog2.org) server.
3b910c3 @Seldaek Rewrap README
authored
112 - _SocketHandler_: Logs records to [sockets](http://php.net/fsockopen), use this
113 for UNIX and TCP sockets. See an [example](https://github.com/Seldaek/monolog/blob/master/doc/sockets.md).
89b5a3c @Seldaek Cosmetic fixes
authored
114 - _AmqpHandler_: Logs records to an [amqp](http://www.amqp.org/) compatible
115 server. Requires the [php-amqp](http://pecl.php.net/package/amqp) extension (1.0+).
7c2ca1c @Seldaek CubeHandler cleanup
authored
116 - _CubeHandler_: Logs records to a [Cube](http://square.github.com/cube/) server.
580df22 @Seldaek Updated README to document all existing handlers
authored
117
118 Wrappers / Special Handlers
119 ---------------------------
120
3b910c3 @Seldaek Rewrap README
authored
121 - _FingersCrossedHandler_: A very interesting wrapper. It takes a logger as
122 parameter and will accumulate log records of all levels until a record
123 exceeds the defined severity level. At which point it delivers all records,
124 including those of lower severity, to the handler it wraps. This means that
125 until an error actually happens you will not see anything in your logs, but
126 when it happens you will have the full information, including debug and info
127 records. This provides you with all the information you need, but only when
128 you need it.
129 - _NullHandler_: Any record it can handle will be thrown away. This can be used
130 to put on top of an existing handler stack to disable it temporarily.
131 - _BufferHandler_: This handler will buffer all the log records it receives
cac3860 @msabramo README.mdown tweaks
msabramo authored
132 until `close()` is called at which point it will call `handleBatch()` on the
3b910c3 @Seldaek Rewrap README
authored
133 handler it wraps with all the log messages at once. This is very useful to
134 send an email with all records at once for example instead of having one mail
135 for every log record.
136 - _GroupHandler_: This handler groups other handlers. Every record received is
137 sent to all the handlers it is configured with.
138 - _TestHandler_: Used for testing, it records everything that is sent to it and
139 has accessors to read out the information.
8d27400 @Seldaek Updated README
authored
140
0ce2cb2 @Seldaek Updated README
authored
141 Formatters
142 ----------
143
144 - _LineFormatter_: Formats a log record into a one-line string.
0bd4d93 @Seldaek Split off line formatter in normalizer + line formatters
authored
145 - _NormalizerFormatter_: Normalizes objects/resources down to strings so a record can easily be serialized/encoded.
0ce2cb2 @Seldaek Updated README
authored
146 - _JsonFormatter_: Encodes a log record into json.
147 - _WildfireFormatter_: Used to format log records into the Wildfire/FirePHP protocol, only useful for the FirePHPHandler.
8d4ac5c @Seldaek Rename ChromePhp to ChromePHP for consistency with FirePHP
authored
148 - _ChromePHPFormatter_: Used to format log records into the ChromePHP format, only useful for the ChromePHPHandler.
4b2c47d @Seldaek Update README/CHANGELOG
authored
149 - _GelfFormatter_: Used to format log records into Gelf message instances, only useful for the GelfHandler.
0ce2cb2 @Seldaek Updated README
authored
150
151 Processors
152 ----------
153
f93d6f0 @Seldaek Added IntrospectionProcessor: Adds the line/file/class/method from wh…
authored
154 - _IntrospectionProcessor_: Adds the line/file/class/method from which the log call originated.
0ce2cb2 @Seldaek Updated README
authored
155 - _WebProcessor_: Adds the current request URI, request method and client IP to a log record.
fe0b8b5 @Seldaek Updated CHANGELOG & README
authored
156 - _MemoryUsageProcessor_: Adds the current memory usage to a log record.
157 - _MemoryPeakUsageProcessor_: Adds the peak memory usage to a log record.
0ce2cb2 @Seldaek Updated README
authored
158
159 About
160 =====
161
8d27400 @Seldaek Updated README
authored
162 Requirements
163 ------------
164
6b64c76 @wilmoore Added note to README regarding phpunit 3.5+ being necessary in order to
wilmoore authored
165 - Any flavor of PHP 5.3 should do
166 - [optional] PHPUnit 3.5+ to execute the test suite (phpunit --version)
8d27400 @Seldaek Updated README
authored
167
6dd6f04 @stof Updated README
stof authored
168 Submitting bugs and feature requests
169 ------------------------------------
170
cf06541 @Seldaek Adjusments to docs/readme
authored
171 Bugs and feature request are tracked on [GitHub](https://github.com/Seldaek/monolog/issues)
6dd6f04 @stof Updated README
stof authored
172
2ff85ba @Seldaek Added README file
authored
173 Author
174 ------
175
7f2127b @Seldaek Updated README
authored
176 Jordi Boggiano - <j.boggiano@seld.be> - <http://twitter.com/seldaek><br />
20110bf @Seldaek Updated README
authored
177 See also the list of [contributors](https://github.com/Seldaek/monolog/contributors) which participated in this project.
2ff85ba @Seldaek Added README file
authored
178
179 License
180 -------
181
cac3860 @msabramo README.mdown tweaks
msabramo authored
182 Monolog is licensed under the MIT License - see the `LICENSE` file for details
2ff85ba @Seldaek Added README file
authored
183
3fa6e4b @Seldaek Major refactoring to follow the Logbook model
authored
184 Acknowledgements
185 ----------------
186
3b910c3 @Seldaek Rewrap README
authored
187 This library is heavily inspired by Python's [Logbook](http://packages.python.org/Logbook/)
188 library, although most concepts have been adjusted to fit to the PHP world.
Something went wrong with that request. Please try again.