JBoss.orgCommunity Documentation

Chapter 3. JBoss AS Crash Course

3.1. Configuring
3.2. Running
3.3. Deploying
3.4. Logging
3.4.1. TorqueBox::Logger
3.4.2. JBoss Logging Configuration

The JBoss Application Server (AS7) is the foundation upon which TorqueBox is built. You can go a long way with TorqueBox without knowing anything about the administration of JBoss AS, but for advanced applications, it's worth knowing something about how AS is configured and extended. Feel free to skip this section if you're just getting started with TorqueBox, and use it as a reference later.

For more detailed documentation, please read the official AS7 docs.

JBoss AS7 has extensive changes since the previous releases, the most visible being folder structure and runtime modes: domain and standalone.

In AS7, all server configuration is kept in two folders for each runtime mode: standalone and domain. Administrative tasks are simplified from previous releases because all configuration is in one folder and, in standalone mode, in a single file.

TorqueBox uses standalone mode by default but can be run in domain mode as well.

JBoss AS 7 uses a modular architecture - libraries common to all server configurations are kept under the modules/ directory. Configuration files are stored inside standalone/configuration/ and domain/configuration/ folders.

Both standalone and domain modes have a common folder structure, including the following directories: configuration/, deployments/ and lib/. In general, it isn't a good idea to remove anything from these directories that you didn't put there yourself.

Some additional directories are created automatically at runtime, as needed: tmp/, data/, and log/. Though not typically necessary, you may safely delete these when the server is not running to clear its persistent state.

The $JBOSS_HOME/bin/ directory contains the main JBoss entry point, standalone.sh (or standalone.bat), along with its config file, standalone.conf. Running the JBoss server is simple:

 $ $JBOSS_HOME/bin/standalone.sh 

Use the --server-config option to specify a different configuration. For example, to put JBoss in "clustered" mode:

 $ $JBOSS_HOME/bin/standalone.sh --server-config=standalone-ha.xml

You may set Java system properties using the -D option. Pass -h for a list of all the available options.

Permanent runtime configuration of JBoss should go in bin/standalone.conf. For example, your application may require more memory (RAM) than the default allocated. Edit standalone.conf to increase the value of -Xmx to something reasonable.

Though Chapter 19, TorqueBox Capistrano Support doesn't strictly require it, in production you may prefer to control JBoss via a Unix "init script", examples of which may be found in bin/. Feel free to tweak one for your particular OS.

We also provide support for managing TorqueBox via upstart. See Section 18.4, “Server control” for more details.

Each runtime mode has a deployments/ subdirectory, the contents of which determine the applications and services JBoss runs. These apps and services are represented as archives or text files called "deployment descriptors". TorqueBox provides Rake tasks and a torquebox to aid the deployment process. For more details, see Chapter 4, TorqueBox Application Deployment and Chapter 5, TorqueBox Deployment Descriptors.

Here we'll focus on the default JBoss configuration and how to expose the JBoss logging system to your Ruby applications, if so desired.

JBoss provides a very sophisticated logging system that nobody completely understands. It's possible to configure hierarchical, categorized log message routing, complex file rotation, syslog integration, SMTP notifications, SNMP traps, JMS, JMX and much more. Obviously, most of that is far beyond the scope of this document.

All JBoss log messages, just like Ruby ones, have an associated level, e.g. DEBUG, INFO, WARN, ERROR, or FATAL. These levels are ordered by increasing severity, e.g. FATAL is higher than ERROR, which is higher than WARN, etc. Unlike messages from a Ruby Logger, each JBoss log message also has a category. Logging configuration rules determine where messages are logged according to their category and level. These rules are contained in the logging subsystem element of standalone/configuration/standalone.xml. By default, you will see INFO (and higher, i.e. more severe) messages on the console (the shell where you start TorqueBox) and written persistently to standalone/log/server.log.

Anything written to stdout or stderr is interpreted as an INFO log message and will therefore also be displayed on the console and written to standalone/log/server.log.

Of course, standard Ruby Loggers work fine inside of TorqueBox, and you'll find your Rails log files exactly where you expect them to be (unless your app is archived, in which case they'll reside beneath standalone/log/). But some users, especially those already familiar with Java logging, may prefer for some Ruby log messages to be passed to JBoss. This is easily achieved using the TorqueBox::Logger. For example, you may configure your Rails app like so:

config.logger = TorqueBox::Logger.new

This results in all Rails-generated log messages being passed to JBoss, hence written to standalone/log/server.log in the default configuration. The category for these messages will be the application's name. You can override this by passing the category name in the constructor:

TorqueBox::Logger.new( "Billing" )

You may pass any type of object to the constructor as long as it responds to :to_s. A common convention is to use a class name as a category in Java applications. You can do the same with Ruby:

@logger = TorqueBox::Logger.new( self.class )

If the class is defined in a module, its name will be something like YourModule::YourClass. The logger will replace the double-colons (::) with a period (.), yielding YourModule.YourClass as the category. This is because categories are hierarchical and delimited by a period, enabling you to define rules for all classes in the same module, for example.

It's important to understand that, although the TorqueBox::Logger does honor the Ruby Logger interface, setting its :level attribute will have no effect. The only configuration it honors is JBoss', e.g. the logging subsystem element in standalone/configuration/standalone.xml

The default AS 7.1 configuration is shown below. It includes two handlers (one for the CONSOLE and one for the FILE), some loggers and a root logger. When a message is logged, here's what happens:

One thing to note about the default logging configuration is that DEBUG messages won't show up anywhere. So, for example, the following log message will be discarded:

        @logger = TorqueBox::Logger.new( YourModule::YourClass )
        @logger.debug("Will code for food")

This is because the "YourModule.YourClass" category matches no logger and its level (DEBUG) is lower than the default level for the root logger (INFO). One solution is to lower the default level for the root logger to DEBUG, but that results in DEBUG messages for every other category that doesn't match any of the loggers, potentially a lot of messages. A better solution is to define a <logger> specifically for the category:

        <logger category='YourModule.YourClass'>
          <level name='DEBUG'/>

This will result in log messages written to the FILE handler, but not the CONSOLE, since its threshold level is still set at INFO.

For many applications, it's usually better to take advantage of the hierarchical nature of categories and refer only to the module name so that any logger associated with any class within that module will match:

        <logger category='YourModule'>
          <level name='DEBUG'/>

For more information, see the official JBoss logging documentation.