Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Commenting out doc on log mutator functions as the feature does not p…

…resently work.
  • Loading branch information...
commit b539c71ec1ecadbac59c62708ca9bd813f82c4e9 1 parent 11379a5
@zhouyaoji authored
Showing with 126 additions and 103 deletions.
  1. +126 −103 docs/dev_guide/topics/mojito_logging.rst
View
229 docs/dev_guide/topics/mojito_logging.rst
@@ -4,12 +4,13 @@
Logging
=======
-Mojito has its own logging system. When you call ``Y.log`` from within your mojits, your log messages are intercepted and processed by Mojito. This allows you
-to create your own log formatting, writing, and publishing functions for both your client and server runtimes. It also allows you to enable log buffering,
-so performance during crucial runtime periods is not adversely affected.
+Mojito has its own logging system. When you call ``Y.log`` from within your mojits, your log
+messages are intercepted and processed by Mojito. This allows you to create your own log formatting,
+writing, and publishing functions for both your client and server runtimes. It also allows you to
+enable log buffering, so performance during crucial runtime periods is not adversely affected.
Log Levels
-##########
+==========
Mojito has the following five log levels:
@@ -19,22 +20,26 @@ Mojito has the following five log levels:
- ``ERROR``
- ``MOJITO``
-All of them should be familiar except the last, which are framework-level messages that indicate that an important framework event is occurring (one that users might want to track).
+All of them should be familiar except the last, which are framework-level messages that indicate that
+an important framework event is occurring (one that users might want to track).
-Setting a log level of ``WARN`` will filter out all ``DEBUG`` and ``INFO`` messages, while ``WARN``, ``ERROR``, and ``MOJITO`` log messages will be processed. To see all
+Setting a log level of ``WARN`` will filter out all ``DEBUG`` and ``INFO`` messages, while ``WARN``,
+``ERROR``, and ``MOJITO`` log messages will be processed. To see all
log messages, set the log level to ``DEBUG``.
YUI Library Logs
-################
+================
-By default, all log messages generated by the YUI library itself are processed. The log level filter is also applied to these messages, but within the Mojito log output,
-a "YUI-" identifier is added to them. So when YUI emits a ``WARN`` level log message, the Mojito logs will display a ``YUI-WARN`` log level. This helps differentiate between
-application messages and YUI framework messages.
+By default, all log messages generated by the YUI library itself are processed. The log level filter
+is also applied to these messages, but within the Mojito log output, a "YUI-" identifier is added to
+them. So when YUI emits a ``WARN`` level log message, the Mojito logs will display a ``YUI-WARN``
+log level. This helps differentiate between application messages and YUI framework messages.
-YUI logs can be turned on and off for both server and client within an application's log configuration (see below).
+YUI logs can be turned on and off for both server and client within an application's log configuration
+(see below).
Log Defaults
-############
+============
The server and client log settings have the following default values:
@@ -46,10 +51,12 @@ The server and client log settings have the following default values:
- ``defaultLevel: 'info'`` - if ``Y.log`` is called without a log level, this is the default.
Log Configuration
-#################
+=================
-All the values above are configurable through the `log object <../intro/mojito_configuring.html#log-object>`_ in the ``application.json`` file. In the example ``application.json``
-below, the ``log`` object has both ``client`` and ``server`` objects that override the defaults for ``level`` and ``yui``.
+All the values above are configurable through the
+`log object <../intro/mojito_configuring.html#log-object>`_ in the ``application.json`` file. In the
+example ``application.json`` below, the ``log`` object has both ``client`` and ``server`` objects
+that override the defaults for ``level`` and ``yui``.
.. code-block:: javascript
@@ -70,95 +77,108 @@ below, the ``log`` object has both ``client`` and ``server`` objects that overri
}
]
-Mutator Log Functions
-#####################
-
-You can create different write function to change the format of log messages and control where the logs are written. The logger has functions for formatting, writing,
-and publishing log messages that can be provided by a Mojito application. The function names are defined by users. For example, you could name the log formatter
-either ``formatLogs`` or ``log_formatter``.
-
-Custom Log Formatter
-====================
-
-The log formatter function accepts the log message, the log level, a string identifying the source of the log (usually the YUI module name emitting the log), a timestamp,
-and the complete ``logOptions`` object. The function returns a string, which is passed to the log writer.
-
-.. code-block:: javascript
-
- function {log_formatter_name}(message, logLevel, source, timestamp, logOptions) {
- return "formatted message";
- }
-
-Custom Log Writer
-=================
-
-The log writer function accepts a string and does something with it. You can provide a function that does whatever you want with the log string. The default log writer
-calls ``console.log``.
-
-.. code-block:: javascript
-
- function {log_writer_name}(logMessage[s]) {}
-
-.. note:: Your log writer function must be able to handle a string or an array of strings. If you have set buffered logging, it may be sent an array of formatted log messages.
-
-Custom Log Publisher
-====================
-
-If a log publisher function is provided, it is expected to format and write logs. Thus, a log publisher function takes the place of the log formatter and the log writer functions
-and accepts the same parameters as the log formatter function.
-
-.. code-block:: javascript
-
- function {log_publisher_name}(message, logLevel, source, timestamp, logOptions) {
-
-Custom Log Functions on the Client
-==================================
-
-To provide custom log function on the client, you add the log function to a JavaScript asset that your application will load.
-
-In the example JavaScript asset below, the log function ``formatter`` is first defined and then set as the log formatter function.
-
-.. code-block:: javascript
-
- function formatter(msg, lvl, src, ts, opts) {
- return "LOG MSG: " + msg.toLowerCase() + " -[" + lvl.toUpperCase() + "]- (" + ts + ")";
- }
- YUI._mojito.logger.set('formatter', formatter);
-
-Using the ``formatter`` function above, the log messages will have the following format:
-
-``>LOG MSG: dispatcher loaded and waiting to rock! -[INFO]- (1305666208939)``
-
-Custom Log Functions on the Server
-==================================
-
-On the server, you must add log mutator functions to ``server.js``, so that Mojito will set them as the log functions before starting the server.
-
-In this example ``server.js``, ``writeLog`` writes logs to the file system.
-
-.. code-block:: javascript
-
- var mojito = require('mojito'), fs = require('fs'), logPath = "/tmp/mojitolog.txt";
- function writeLog(msg) {
- fs.writeFile(logPath, msg, 'utf-8');
- }
- // You can access log formatter, writer, or
- // publisher for the server here.
- mojito.setLogWriter(function(logMessage) {
- writeLog(logMessage + '\n');
- });
- module.exports = mojito.createServer();
+.. Commenting out Mutator Log Function documentation because as of 10/03/12, you
+.. cannot create log mutator functions.
+
+ Mutator Log Functions
+ =====================
+
+ You can create different write function to change the format of log messages and control where the
+ logs are written. The logger has functions for formatting, writing, and publishing log messages that
+ can be provided by a Mojito application. The function names are defined by users. For example, you
+ could name the log formatter either ``formatLogs`` or ``log_formatter``.
+
+ Custom Log Formatter
+ --------------------
+
+ The log formatter function accepts the log message, the log level, a string identifying the source
+ of the log (usually the YUI module name emitting the log), a timestamp, and the complete
+ ``logOptions`` object. The function returns a string, which is passed to the log writer.
+
+ .. code-block:: javascript
+
+ function {log_formatter_name}(message, logLevel, source, timestamp, logOptions) {
+ return "formatted message";
+ }
+
+ Custom Log Writer
+ -----------------
+
+ The log writer function accepts a string and does something with it. You can provide a function that
+ does whatever you want with the log string. The default log writer calls ``console.log``.
+
+ .. code-block:: javascript
+
+ function {log_writer_name}(logMessage[s]) {}
+
+ .. note:: Your log writer function must be able to handle a string or an array of strings. If you
+ have set buffered logging, it may be sent an array of formatted log messages.
+
+ Custom Log Publisher
+ --------------------
+
+ If a log publisher function is provided, it is expected to format and write logs. Thus, a log
+ publisher function takes the place of the log formatter and the log writer functions
+ and accepts the same parameters as the log formatter function.
+
+ .. code-block:: javascript
+
+ function {log_publisher_name}(message, logLevel, source, timestamp, logOptions) {
+
+ Custom Log Functions on the Client
+ ----------------------------------
+
+ To provide custom log function on the client, you add the log function to a JavaScript asset that
+ your application will load.
+
+ In the example JavaScript asset below, the log function ``formatter`` is first defined and then set
+ as the log formatter function.
+
+ .. code-block:: javascript
+
+ function formatter(msg, lvl, src, ts, opts) {
+ return "LOG MSG: " + msg.toLowerCase() + " -[" + lvl.toUpperCase() + "]- (" + ts + ")";
+ }
+ YUI._mojito.logger.set('formatter', formatter);
+
+ Using the ``formatter`` function above, the log messages will have the following format:
+
+ ``>LOG MSG: dispatcher loaded and waiting to rock! -[INFO]- (1305666208939)``
+
+ Custom Log Functions on the Server
+ ----------------------------------
+
+ On the server, you must add log mutator functions to ``server.js``, so that Mojito will set them as
+ the log functions before starting the server.
+
+ In this example ``server.js``, ``writeLog`` writes logs to the file system.
+
+ .. code-block:: javascript
+
+ var mojito = require('mojito'), fs = require('fs'), logPath = "/tmp/mojitolog.txt";
+ function writeLog(msg) {
+ fs.writeFile(logPath, msg, 'utf-8');
+ }
+ // You can access log formatter, writer, or
+ // publisher for the server here.
+ mojito.setLogWriter(function(logMessage) {
+ writeLog(logMessage + '\n');
+ });
+ module.exports = mojito.createServer();
Log Buffering
-#############
+=============
-To avoid performance issues caused by logging, you can enable buffering, which will configure Mojito to cache all logs in memory. You can force Mojito to flush the logs with
-the ``Y.log`` function or setting the maximum buffer size. The following sections show you how to enable buffering and force Mojito to flush the cached logs.
+To avoid performance issues caused by logging, you can enable buffering, which will configure Mojito
+to cache all logs in memory. You can force Mojito to flush the logs with the ``Y.log`` function or
+setting the maximum buffer size. The following sections show you how to enable buffering and force
+Mojito to flush the cached logs.
Enable Buffering
-================
+----------------
-To configure Mojito to buffer your logs, set the ``buffer`` property to ``true`` in the ``log`` object as shown in the example ``application.json`` below.
+To configure Mojito to buffer your logs, set the ``buffer`` property to ``true`` in the ``log``
+object as shown in the example ``application.json`` below.
.. code-block:: javascript
@@ -178,13 +198,16 @@ To configure Mojito to buffer your logs, set the ``buffer`` property to ``true`
]
Flush Cached Logs
-=================
+-----------------
-Mojito provides you with two ways to forcefully flush cached logs. When you have buffering enabled, you can force Mojito to flush the cached logs with ``Y.log(({flush: true})``.
-You can also set the maximum buffer size, so that Mojito will flush cached logs after the cache has reached the maximum buffer size.
+Mojito provides you with two ways to forcefully flush cached logs. When you have buffering enabled,
+you can force Mojito to flush the cached logs with ``Y.log(({flush: true})``. You can also set the
+maximum buffer size, so that Mojito will flush cached logs after the cache has reached the maximum
+buffer size.
-In the example ``application.json`` below, the maximum buffer size is set to be 4096 bytes. Once the log cache reaches this size, the logs are then flushed. The default size of
-the log cache is 1024 bytes.
+In the example ``application.json`` below, the maximum buffer size is set to be 4096 bytes. Once the
+log cache reaches this size, the logs are then flushed. The default size of the log cache is 1024
+bytes.
.. code-block:: javascript
Please sign in to comment.
Something went wrong with that request. Please try again.