basis/logging/logging-docs.factor

   1 USING: help.markup help.syntax logging.server quotations strings
   2 words ;
   3 IN: logging
   4
   5 HELP: DEBUG
   6 { $description "Log level for debug messages." } ;
   7
   8 HELP: NOTICE
   9 { $description "Log level for ordinary messages." } ;
  10
  11 HELP: WARNING
  12 { $description "Log level for warnings." } ;
  13
  14 HELP: ERROR
  15 { $description "Log level for error messages." } ;
  16
  17 HELP: CRITICAL
  18 { $description "Log level for critical errors which require immediate attention." } ;
  19
  20 ARTICLE: "logging.levels" "Log levels"
  21 "Several log levels are supported, from lowest to highest:"
  22 { $subsections
  23     DEBUG
  24     NOTICE
  25     WARNING
  26     ERROR
  27     CRITICAL
  28 } ;
  29
  30 ARTICLE: "logging.files" "Log files"
  31 "Each application that wishes to use logging must choose a log service name; the following combinator should wrap the top level of the application:"
  32 { $subsections with-logging }
  33 "Log messages are written to " { $snippet "log-root/service/1.log" } ", where"
  34 { $list
  35     { { $snippet "log-root" } " is " { $snippet "resource:logs" } " by default, but can be overriden with the " { $link log-root } " variable" }
  36     { { $snippet "service" } " is the service name" }
  37 }
  38 "You can get the log path for a service:"
  39 { $subsections
  40     log-path
  41     log#
  42 }
  43 "New log entries are always sent to " { $snippet "1.log" } " but " { $link "logging.rotation" } " moves " { $snippet "1.log" } " to " { $snippet "2.log" } ", " { $snippet "2.log" } " to " { $snippet "3.log" } ", and so on." ;
  44
  45 HELP: log-message
  46 { $values { "msg" string } { "word" word } { "level" "a log level" } }
  47 { $description "Sends a message to the current log if the level is more urgent than " { $link log-level } ". Does nothing if not executing in a dynamic scope established by " { $link with-logging } "." } ;
  48
  49 HELP: add-logging
  50 { $values { "word" word } { "level" "a log level" } }
  51 { $description "Causes the word to log a message every time it is called." } ;
  52
  53 HELP: add-input-logging
  54 { $values { "word" word } { "level" "a log level" } }
  55 { $description "Causes the word to log its input values every time it is called. The word must have a stack effect declaration." } ;
  56
  57 HELP: add-output-logging
  58 { $values { "word" word } { "level" "a log level" } }
  59 { $description "Causes the word to log its output values every time it is called. The word must have a stack effect declaration." } ;
  60
  61 HELP: add-error-logging
  62 { $values { "word" word } { "level" "a log level" } }
  63 { $description "Causes the word to log its input values and any errors it throws."
  64 $nl
  65 "If the word is not executed in a dynamic scope established by " { $link with-logging } ", its behavior is unchanged, and any errors it throws are passed to the caller."
  66 $nl
  67 "If called from a logging context, its input values are logged, and if it throws an error, the error is logged and the word returns normally. Any inputs are popped from the stack and " { $link f } " is pushed in place of each output." } ;
  68
  69 HELP: log-error
  70 { $values { "error" "an error" } { "word" word } }
  71 { $description "Logs an error." } ;
  72
  73 HELP: log-critical
  74 { $values { "error" "an error" } { "word" word } }
  75 { $description "Logs a critical error." } ;
  76
  77 HELP: LOG:
  78 { $syntax "LOG: name level" }
  79 { $values { "name" "a new word name" } { "level" "a log level" } }
  80 { $description "Creates a word with stack effect " { $snippet "( object -- )" } " which logs its input and does nothing else." } ;
  81
  82 ARTICLE: "logging.messages" "Logging messages"
  83 "Logging messages explicitly:"
  84 { $subsections
  85     log-message
  86     log-error
  87     log-critical
  88 }
  89 "A utility for defining words which just log and do nothing else:"
  90 { $subsections POSTPONE: LOG: }
  91 "Annotating words to log; this uses the " { $link "tools.annotations" } " feature:"
  92 { $subsections
  93     add-input-logging
  94     add-output-logging
  95     add-error-logging
  96 } ;
  97
  98 HELP: rotate-logs
  99 { $description "Rotates all logs. The highest numbered log file in each log directory is deleted, and each file is renamed so that its number increments by one. Subsequent logging calls will create a new #1 log file. This keeps log files from getting too large and makes them easier to search." } ;
 100
 101 HELP: close-logs
 102 { $description "Closes all open log streams. Subsequent logging will re-open the streams. This should be used before moving or deleting log files." } ;
 103
 104 HELP: with-logging
 105 { $values { "service" "a log service name" } { "quot" quotation } }
 106 { $description "Calls the quotation a new dynamic scope where all logging calls more urgent than " { $link log-level } " are sent to the log file for " { $snippet "service" } "." } ;
 107
 108 ARTICLE: "logging.rotation" "Log rotation"
 109 "Log files should be rotated periodically to prevent unbounded growth."
 110 { $subsections
 111     rotate-logs
 112     close-logs
 113 }
 114 "The " { $vocab-link "logging.insomniac" } " vocabulary automates log rotation." ;
 115
 116 ARTICLE: "logging.server" "Log implementation"
 117 "The " { $vocab-link "logging.server" } " vocabulary implements a concurrent log server using " { $vocab-link "concurrency.messaging" } ". User code never interacts with the server directly, instead it uses the words in the " { $link "logging" } " vocabulary. The server is used to synchronize access to log files and ensure that log rotation can proceed in an orderly fashion."
 118 $nl
 119 "The " { $link log-message } " word sends a message to the server which results in the server executing an internal word:"
 120 { $subsections (log-message) }
 121 "The " { $link rotate-logs } " word sends a message to the server which results in the server executing an internal word:"
 122 { $subsections (rotate-logs) }
 123 "The " { $link close-logs } " word sends a message to the server which results in the server executing an internal word:"
 124 { $subsections (close-logs) } ;
 125
 126 ARTICLE: "logging" "Logging framework"
 127 "The " { $vocab-link "logging" } " vocabulary implements a comprehensive logging framework suitable for server-side production applications."
 128 { $subsections
 129     "logging.files"
 130     "logging.levels"
 131     "logging.messages"
 132     "logging.rotation"
 133     "logging.parser"
 134     "logging.analysis"
 135     "logging.server"
 136 } ;
 137
 138 ABOUT: "logging"