basis/logging/logging-docs.factor

   1 IN: logging
   2 USING: help.markup help.syntax assocs math calendar
   3 logging.server strings words quotations ;
   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: ERROR
  12 { $description "Log level for error messages." } ;
  13
  14 HELP: CRITICAL
  15 { $description "Log level for critical errors which require immediate attention." } ;
  16
  17 ARTICLE: "logging.levels" "Log levels"
  18 "Several log levels are supported, from lowest to highest:"
  19 { $subsection DEBUG }
  20 { $subsection NOTICE }
  21 { $subsection ERROR }
  22 { $subsection CRITICAL } ;
  23
  24 ARTICLE: "logging.files" "Log files"
  25 "Each application that wishes to use logging must choose a log service name; the following combinator should wrap the top level of the application:"
  26 { $subsection with-logging }
  27 "Log messages are written to " { $snippet "log-root/service/1.log" } ", where"
  28 { $list
  29     { { $snippet "log-root" } " is the Factor source directory by default, but can be overriden with the " { $link log-root } " variable" }
  30     { { $snippet "service" } " is the service name" }
  31 }
  32 "You can get the log path for a service:"
  33 { $subsection log-path }
  34 { $subsection log# }
  35 "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." ;
  36
  37 HELP: log-message
  38 { $values { "msg" string } { "word" word } { "level" "a log level" } }
  39 { $description "Sends a message to the current log. Does nothing if not executing in a dynamic scope established by " { $link with-logging } "." } ;
  40
  41 HELP: add-logging
  42 { $values { "level" "a log level" } { "word" word } }
  43 { $description "Causes the word to log a message every time it is called." } ;
  44
  45 HELP: add-input-logging
  46 { $values { "level" "a log level" } { "word" word } }
  47 { $description "Causes the word to log its input values every time it is called. The word must have a stack effect declaration." } ;
  48
  49 HELP: add-output-logging
  50 { $values { "level" "a log level" } { "word" word } }
  51 { $description "Causes the word to log its output values every time it is called. The word must have a stack effect declaration." } ;
  52
  53 HELP: add-error-logging
  54 { $values { "level" "a log level" } { "word" word } }
  55 { $description "Causes the word to log its input values and any errors it throws."
  56 $nl
  57 "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."
  58 $nl
  59 "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." } ;
  60
  61 HELP: log-error
  62 { $values { "error" "an error" } { "word" word } }
  63 { $description "Logs an error." } ;
  64
  65 HELP: log-critical
  66 { $values { "error" "an error" } { "word" word } }
  67 { $description "Logs a critical error." } ;
  68
  69 HELP: LOG:
  70 { $syntax "LOG: name level" }
  71 { $values { "name" "a new word name" } { "level" "a log level" } }
  72 { $description "Creates a word with stack effect " { $snippet "( object -- )" } " which logs its input and does nothing else." } ;
  73
  74 ARTICLE: "logging.messages" "Logging messages"
  75 "Logging messages explicitly:"
  76 { $subsection log-message }
  77 { $subsection log-error }
  78 { $subsection log-critical }
  79 "A utility for defining words which just log and do nothing else:"
  80 { $subsection POSTPONE: LOG: }
  81 "Annotating words to log; this uses the " { $link "tools.annotations" } " feature:"
  82 { $subsection add-input-logging }
  83 { $subsection add-output-logging }
  84 { $subsection add-error-logging } ;
  85
  86 HELP: rotate-logs
  87 { $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." } ;
  88
  89 HELP: close-logs
  90 { $description "Closes all open log streams. Subsequent logging will re-open the streams. This should be used before moving or deleting log files." } ;
  91
  92 HELP: with-logging
  93 { $values { "service" "a log service name" } { "quot" quotation } }
  94 { $description "Calls the quotation a new dynamic scope where all logging calls are sent to the log file for " { $snippet "service" } "." } ;
  95
  96 ARTICLE: "logging.rotation" "Log rotation"
  97 "Log files should be rotated periodically to prevent unbounded growth."
  98 { $subsection rotate-logs }
  99 { $subsection close-logs }
 100 "The " { $vocab-link "logging.insomniac" } " vocabulary automates log rotation." ;
 101
 102 ARTICLE: "logging.server" "Log implementation"
 103 "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."
 104 $nl
 105 "The " { $link log-message } " word sends a message to the server which results in the server executing an internal word:"
 106 { $subsection (log-message) }
 107 "The " { $link rotate-logs } " word sends a message to the server which results in the server executing an internal word:"
 108 { $subsection (rotate-logs) }
 109 "The " { $link close-logs } " word sends a message to the server which results in the server executing an internal word:"
 110 { $subsection (close-logs) } ;
 111
 112 ARTICLE: "logging" "Logging framework"
 113 "The " { $vocab-link "logging" } " vocabulary implements a comprehensive logging framework suitable for server-side production applications."
 114 { $subsection "logging.files" }
 115 { $subsection "logging.levels" }
 116 { $subsection "logging.messages" }
 117 { $subsection "logging.rotation" }
 118 { $subsection "logging.parser" }
 119 { $subsection "logging.analysis" }
 120 { $subsection "logging.server" } ;
 121
 122 ABOUT: "logging"
 123