Prudence
The Scalable REST/JVM
Web Development Platform
Creative Commons License

Logging

Prudence comes pre-configured with robust logging, based on log4j.
You are encouraged to make use of logging in your applications, but even if you don't, you will still find the logs useful. Prudence's servers, routers, programming languages and other components all send messages to the logs, making them an invaluable tool for debugging, monitoring and understanding how Prudence works.
By default, logs are sent to the /logs/ directory, using configurable rolling log schemes. /logs/web.log records all server requests, using Apache's format, while everything else goes to /logs/prudence.log.

Loggers

The Base Logger

Use application.logger to send text messages to the log. The logger name defaults to your application's subdirectory name, but can be configured via the applicationLoggerName setting.

Sub-Loggers

Large applications might benefit from using more than one logger. Use application.getSubLogger with any name you wish. This name will be appended to your base logger name with a ".", and will inherit the base logger's configuration by default. For example, if your base logger is named "wackywiki", then application.getSubLogger('backend') will appear as "wackiwiki.backend" in the log files.
See more on logger inheritance below.

Sending Messages

Whether messages actually are written to the log file depends on your logging configuration. Messages are ranked by levels, and loggers are configured to allow only messages up to a certain level. Smart, consistent use of log levels will increase the debuggability of your application.
The logging methods and their common uses are these (shown for the base logger, but work the same for sub-loggers):
  1. application.logger.severe: "Severe" messages are used for unrecoverable errors, alerts about unavailable computing resources, network backends, etc. You'd likely always want to configure logging to include at least these messages!
  2. application.logger.warning: While not quite severe, the event could still point out a problem that if not handled might become severe, either now or in the future. Many applications and services emit warnings that can be safely ignored normally, but may be helpful when trying to debug a specific problem.
  3. application.logger.info: These don't report a problem, but instead are used to mark an occurrence of an event. Useful for monitoring and high-level debugging.
  4. application.logger.config: Treat these as components of an event that together would constitute a single "info" message. They are meant to show how the event was initialized or released. Useful for low-level debugging of events.
  5. application.logger.fine: General purpose, low-level debugging.
  6. application.logger.finer: Even lower!
  7. application.logger.finest: Lowest of the low!

/configuration/logging.conf

We'll cover the basics here. See log4j documentation for more information.
The Prudence defaults are mostly at "info" level. You are encouraged to experiment with lower levels in order to see how Prudence's internals function.

Appenders

An "appender" is the service that actually writes log messages. Appenders are configured with properties prefixed with "log4j.appender.X", where X is the name of the appender.
Prudence by default uses two rolling file appenders, one called "web" for web.log, and one called "prudence" for prudence.log. Additionally, a console appender named "console" and a remote appender named "remote" are configured, though they are not used by default.

Loggers

A "logger" is the service to which you send your log messages. It decides whether to write the message according to its level, and if so sends it to one or more appenders. Loggers are configured with properties prefixed with "log4j.logger.X", where X is the name of the logger. Logger names appear in the logs for every message, and are thus useful for organization your log.
You do not have to define all your loggers in logging.conf. Any logger name can be used by your application. If it is not found in logging.conf, then default attributes are inherited. Inheritance works by treating logger names hierarchically: if you do not specify a certain attribute for a logger, then its parent logger is used. The nameless root logger, configured with the "log4j.rootLogger" prefix, defines defaults for all loggers.
You can configure your application's logger and sub-loggers. For example, if your application is named "wackywiki," you can set its maximum logging level thus: 
log4j.logger.wackywiki=WARN
Log levels in logging.conf are named a bit differently from the commands used in application.logger:
  1. OFF: no logging
  2. ERROR: application.logger.severe
  3. WARN: application.logger.warning
  4. INFO: application.logger.info
  5. DEBUG: application.logger.config, application.logger.fine, application.logger.finer
  6. TRACE (or ALL): application.logger.finest
The differences are due to the preponderance of logging solutions for the JVM, which are used in some of Prudence's underlying libraries. We hope to streamline this further in a future version of Prudence.
You can also add or change appenders for your loggers. For example, to send wackywiki messages to the console appender: 
log4j.logger.wackywiki=WARN, console

Separate Logs Per Application

We'll create a new appender for each new log file we need. In this example, we'll just copy the "prudence" appender with a new name: 
log4j.appender.wackywiki=org.apache.log4j.RollingFileAppender
log4j.appender.wackywiki.File=logs/wackywiki.log
log4j.appender.wackywiki.MaxFileSize=5MB
log4j.appender.wackywiki.MaxBackupIndex=9
log4j.appender.wackywiki.layout=org.apache.log4j.PatternLayout
log4j.appender.wackywiki.layout.ConversionPattern=%d: %-5p [%c] %m%n
Then, we'll direct our application logger to use this appender: 
log4j.logger.wackywiki=WARN, wackywiki

Analyzing /logs/web.log

You can throw Prudence's web.log into almost any Apache log file analyzer. Here's an example using the ubiquitous Analog: 
analog \
-C'LOGFORMAT (%Y-%m-%d\t%h:%n:%j\t%S\t%u\t%j\t%j\t%j\t%r\t%q\t%c\t%b\t%j\t%T\t%v\t%B\t%f)' \
-C'LOCALCHARTDIR local/images/' \
-C'CHARTDIR images/' \
-C'HOSTNAME "mysite.org"' \
logs/web.log \
-Oapplications/myapp/web/static/analog/index.html