Overview

Postage is a stand-alone application generating constant mail traffic on a James server instance. It can be considered being a load test tool.

Postage records the resources used by James and supports finding resource leaks, for example memory bottlenecks.

While putting load on James, Postage also records the resulting mail traffic and tries to match incoming and outgoing mail making it possible to use it for end-to-end test.

It's flexible enough to mimic many real-world load scenarios, for example

Features

Prepare

as prerequisites you need

get the latest source code from subversion:

svn checkout http://svn.apache.org/repos/asf/james/postage/trunk postage

cd postage

make sure, that you download and add the following libraries to lib/

from Sun

from a local James build:

Building

to build, type

ant

Postage optionally uses JVM JMX features not available before Java 5. At build time, Postage detects the Java version you are building with and deactivates the Java5 features if you are on Java 1.4. (This works by excluding the Java5 specific class from the build.) At run-time, Postage activates JMX if available and possible:

1.4 build

5.0 build

1.4 runtime

works w/o JMX

fails

5.0 runtime

works w/o JMX

works w/JMX

to compile the jar, type

ant package

Prepare James

You should have a James instance readily installed. This means at least extracted James binary and started the server once (see JamesQuickstart).

1. Edit the configuration file JAMES_HOME/apps/james/SAR-INF/config.xml

1.1. Internal test domain

In the server names sections, add new line containing the virtual domain "mail.james.local". This makes James consume all mails addressed to, for example test@mail.james.local.

It should look something like this, depending on your further configuration preferences:

   <servernames autodetect="true" autodetectIP="true">
<!-- CONFIRM? -->
      <servername>localhost</servername>
      <servername>mail.james.local</servername>
   </servernames>

1.2.Sending external mail

All mail addresses not handled by James are delivered to their intended destination, if possible. For Postage to intercept this and receive all mails send out by James, we must enable gateway forwarding.

change

   <!--
      <gateway> otherserver.mydomain.com </gateway>
      <gatewayPort>25</gatewayPort>
   -->

into

   <gateway> localhost </gateway>
   <gatewayPort>2525</gatewayPort>

If Postage is running on another machine than James, you should use the appropriate host/port combination under which Postage is receiving mail.

Now Postage is consuming all mail sent out by James and tries to align the mail it puts into James with mail coming out of the server.

NOTE: This configuration makes James unable to deliver regular external mail, don't do this on a production system!

2. Enable Postage to record memory and thread resource consumption of James

This is optional configuration.

It only works, if James is run under JSE5 or newer and only if Postage has been build with JMX support. It also conflicts with James' current genuine MX4J-based JMX support, which has to be disabled (see ConfigureJmx how to use JSE5 JMX support).

Edit file <JAMES_HOME>/bin/phoenix.[sh|bat]

Replace line

JVM_OPTS="-Djava.ext.dirs=$JVM_EXT_DIRS"

with (on one line)

JVM_OPTS="-Djava.ext.dirs=$JVM_EXT_DIRS -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.port=10201 "

Configure Postage

At startup, you can provide Postage with a configuration file on the command line. The configuration file is split up into sections called scenarios. Each scenarios stands for one postage run with a set of result files. You would typically choose one scenario to be run, but you can run an arbitrary sequence of scenarios.

See the configuration file distributed with Postage for detailed documentation. You'll find postage.xml in config/ or in svn at http://svn.apache.org/repos/asf/james/postage/trunk/src/main/config/postage.xml .

For your own scenario just copy/paste an existing scenario, give it a new ID and start modifying it.

Existing scenarios cover

debug

used in Postage development

release

to test a James build before release

release_james512

test case to reproduce JIRA JAMES-512

extended_resources

scenario which takes more from James than the default resources

Running

ant run

TODO: elaborate on running a specific scenario

JamesPostage (last edited 2009-09-20 22:58:28 by localhost)