Skip to content
Newer
Older
100644 186 lines (142 sloc) 7.63 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.
109 - _SwiftMailerHandler_: Sends emails using a `Swift_Mailer` 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).
580df22 @Seldaek Updated README to document all existing handlers
authored
114
115 Wrappers / Special Handlers
116 ---------------------------
117
3b910c3 @Seldaek Rewrap README
authored
118 - _FingersCrossedHandler_: A very interesting wrapper. It takes a logger as
119 parameter and will accumulate log records of all levels until a record
120 exceeds the defined severity level. At which point it delivers all records,
121 including those of lower severity, to the handler it wraps. This means that
122 until an error actually happens you will not see anything in your logs, but
123 when it happens you will have the full information, including debug and info
124 records. This provides you with all the information you need, but only when
125 you need it.
126 - _NullHandler_: Any record it can handle will be thrown away. This can be used
127 to put on top of an existing handler stack to disable it temporarily.
128 - _BufferHandler_: This handler will buffer all the log records it receives
cac3860 @msabramo README.mdown tweaks
msabramo authored
129 until `close()` is called at which point it will call `handleBatch()` on the
3b910c3 @Seldaek Rewrap README
authored
130 handler it wraps with all the log messages at once. This is very useful to
131 send an email with all records at once for example instead of having one mail
132 for every log record.
133 - _GroupHandler_: This handler groups other handlers. Every record received is
134 sent to all the handlers it is configured with.
135 - _TestHandler_: Used for testing, it records everything that is sent to it and
136 has accessors to read out the information.
8d27400 @Seldaek Updated README
authored
137
0ce2cb2 @Seldaek Updated README
authored
138 Formatters
139 ----------
140
141 - _LineFormatter_: Formats a log record into a one-line string.
0bd4d93 @Seldaek Split off line formatter in normalizer + line formatters
authored
142 - _NormalizerFormatter_: Normalizes objects/resources down to strings so a record can easily be serialized/encoded.
0ce2cb2 @Seldaek Updated README
authored
143 - _JsonFormatter_: Encodes a log record into json.
144 - _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
145 - _ChromePHPFormatter_: Used to format log records into the ChromePHP format, only useful for the ChromePHPHandler.
4b2c47d @Seldaek Update README/CHANGELOG
authored
146 - _GelfFormatter_: Used to format log records into Gelf message instances, only useful for the GelfHandler.
0ce2cb2 @Seldaek Updated README
authored
147
148 Processors
149 ----------
150
f93d6f0 @Seldaek Added IntrospectionProcessor: Adds the line/file/class/method from wh…
authored
151 - _IntrospectionProcessor_: Adds the line/file/class/method from which the log call originated.
0ce2cb2 @Seldaek Updated README
authored
152 - _WebProcessor_: Adds the current request URI, request method and client IP to a log record.
fe0b8b5 @Seldaek Updated CHANGELOG & README
authored
153 - _MemoryUsageProcessor_: Adds the current memory usage to a log record.
154 - _MemoryPeakUsageProcessor_: Adds the peak memory usage to a log record.
0ce2cb2 @Seldaek Updated README
authored
155
156 About
157 =====
158
8d27400 @Seldaek Updated README
authored
159 Requirements
160 ------------
161
6b64c76 @wilmoore Added note to README regarding phpunit 3.5+ being necessary in order to
wilmoore authored
162 - Any flavor of PHP 5.3 should do
163 - [optional] PHPUnit 3.5+ to execute the test suite (phpunit --version)
8d27400 @Seldaek Updated README
authored
164
6dd6f04 @stof Updated README
stof authored
165 Submitting bugs and feature requests
166 ------------------------------------
167
cf06541 @Seldaek Adjusments to docs/readme
authored
168 Bugs and feature request are tracked on [GitHub](https://github.com/Seldaek/monolog/issues)
6dd6f04 @stof Updated README
stof authored
169
2ff85ba @Seldaek Added README file
authored
170 Author
171 ------
172
7f2127b @Seldaek Updated README
authored
173 Jordi Boggiano - <j.boggiano@seld.be> - <http://twitter.com/seldaek><br />
20110bf @Seldaek Updated README
authored
174 See also the list of [contributors](https://github.com/Seldaek/monolog/contributors) which participated in this project.
2ff85ba @Seldaek Added README file
authored
175
176 License
177 -------
178
cac3860 @msabramo README.mdown tweaks
msabramo authored
179 Monolog is licensed under the MIT License - see the `LICENSE` file for details
2ff85ba @Seldaek Added README file
authored
180
3fa6e4b @Seldaek Major refactoring to follow the Logbook model
authored
181 Acknowledgements
182 ----------------
183
3b910c3 @Seldaek Rewrap README
authored
184 This library is heavily inspired by Python's [Logbook](http://packages.python.org/Logbook/)
185 library, although most concepts have been adjusted to fit to the PHP world.
Something went wrong with that request. Please try again.