1 /**
  2  * Library for writing to and accessing a debug log.
  3  * @type object
  4  * @constructor
  5  * @class Library for writing to and accessing a debug log. Each log entry has a date, some identifying information, a severity, and a message body. Exceptions that cause requests to fail are automatically logged at severity level FATAL. Limits: Currently only the most recent 1000-1500 messages are stored, and bodies may be up to 1k in length. 
  6  */
  7 var dlog = {}
  8 
  9 /**
 10  * @fileOverview <p>Library for writing to and accessing a debug log. Each log entry has a date, some identifying information, a severity, and a message body.</p> <p>Exceptions that cause requests to fail are automatically logged at severity level FATAL.</p><p>Limits: Currently only the most recent 1000-1500 messages are stored, and bodies may be up to 1k in length.</p>
 11  *
 12  * @example
 13 import("dlog");
 14 
 15 dlog.info("request from IP: ", request.clientAddr);
 16 dlog.info("request path is: ", request.path);
 17 
 18 if (somethingBad()) {
 19   dlog.warn("something bad happened");
 20 }
 21  *
 22  */
 23 
 24 /**
 25  * Severity level FATAL.
 26  * @type number
 27  */
 28 dlog.FATAL        = 0;
 29 /**
 30  * Severity level ERROR.
 31  * @type number
 32  */
 33 dlog.ERROR        = 1;
 34 /**
 35  * Severity level WARN.
 36  * @type number
 37  */
 38 dlog.WARN         = 2;
 39 /**
 40  * Severity level INFO.
 41  * @type number
 42  */
 43 dlog.INFO         = 3;
 44 
 45 /**
 46  * @ignore
 47  */
 48 function _doLog(severity, messages) {
 49   var output = "";
 50   messages.forEach(function(message) {
 51     output += toHTML(message);
 52   });
 53 
 54   appjet._native.debug_log(severity, output);
 55 }
 56 
 57 
 58 /**
 59  * <p>Writes a message of the given severity to the debug log. In addition to the severity and message text, the debug log also tracks: the time the message is logged; the ID of the request that generated the message; and the type (preview, published, or shell) of the request that generated the message.</p>
 60  *
 61  * @param {number} severity The severity of the message.
 62  * @param {*} message The message to log.
 63  * @param {*} etc ...
 64  */
 65 dlog.log = function(severity, message, etc) {
 66   if (typeof(severity) != 'number')
 67     throw new TypeError("Specify log message severity as a number.");
 68   var args = Array.prototype.slice.call(arguments, 1);
 69   _doLog(severity, args);
 70 }
 71 
 72 /**
 73  * <p>Logs a fatal message. "Fatal" is generally used to indicate that execution cannot continue.</p>
 74  *
 75  * @param {*} message The message to log.
 76  * @param {*} etc ...
 77  */
 78 dlog.fatal = function(message, etc) {
 79   _doLog(dlog.FATAL, Array.prototype.slice.call(arguments));
 80 }
 81 
 82 /**
 83  * <p>Logs an error message. "Error" is generally used when something bad and unexpected has happened.</p>
 84  *
 85  * @param {*} message The message to log.
 86  * @param {*} etc ...
 87  */
 88 dlog.error = function(message, etc) {
 89   _doLog(dlog.ERROR, Array.prototype.slice.call(arguments));
 90 }
 91 
 92 /**
 93  * <p>Logs a warning message. "Warn" is generally used when something unexpected happened - perhaps a harbinger of greater errors to come.</p>
 94  *
 95  * @param {*} message The message to log.
 96  * @param {*} etc ...
 97  */
 98 dlog.warn = function(message, etc) {
 99   _doLog(dlog.WARN, Array.prototype.slice.call(arguments));
100 }
101 
102 /**
103  * <p>Logs an info message. "Info" is generally used to note that something interesting has happened.</p>
104  *
105  * @param {*} message The message to log.
106  * @param {*} etc ...
107  */
108 dlog.info = function(message, etc) {
109   _doLog(dlog.INFO, Array.prototype.slice.call(arguments));
110 }
111 
112 /**
113  * <p>Provides programmatic access to the debug log's messages (for making your own dashboard, perhaps?).</p>
114  *
115  * <p>The returned objects have fields that correspond to all recorded information about the message, namely:</p>
116  *
117  * <ul>
118  * <li><strong>date:</strong> the message's date, in milliseconds since the epoch (UNIX time), suitable for passing to the Date constructor.</li>
119  * <li><strong>requestId:</strong> the ID of the request that logged this message.</li>
120  * <li><strong>requestType:</strong> the type of the request that logged this message ("preview", "published", or "shell").</li>
121  * <li><strong>severity:</strong> the severity of the message.</li>
122  * <li><strong>message:</strong> the logged message text.</li>
123  * </ul>
124  *
125  * @param {object} [params] Optional object with the following six optional properties:
126  * @param {number} [params.howOld] How far back (in milliseconds) to access logged messages. Default: 1 hour.
127  * @param {string} [params.idFilter] Only show messages created with this request ID. Default: no rescriction.
128  * @param {boolean} [params.preview] <strong>true</strong> to show messages generated from preview requests. Default: true.
129  * @param {boolean} [params.published] <strong>true</strong> to show messages generated from requests to the published app. Default: true.
130  * @param {boolean} [params.shell] <strong>true</strong> to show messages generated by the shell. Default: false.
131  * @param {number} [params.maxSeverity] The least severe message severity to show (all messages with a severity level <em>more</em> or equally severe will be returned). Default: 4.
132  *
133  * @return {array} An array of objects describing the logged messages.
134  */
135 dlog.messages = function(params) {
136   if (! params) params = {};
137   if (params.preview === undefined)
138     params.preview = true;
139   if (params.published === undefined)
140     params.published = true;
141 
142   return appjet._native.debug_messages(
143     params.howOld || 3600000,
144     params.idFilter || "",
145     params.preview | (params.published << 1) | (params.shell << 2),
146     params.maxSeverity || 4);
147 }
148 
149 /**
150  * <p>Clears the debug log.</p>
151  */
152 dlog.clear = function() {
153   appjet._native.debug_clear();
154 }
155