Skip to content

HTTPS clone URL

Subversion checkout URL

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