The file system.xml defines a set of fields that configure the NetKernel microkernel. Many of these values can be set using the Kernel Parameter Manager. The config parameters can be classified as follows:

1. Paths filesystem locations of key data
2. Throttle parameters that shape the incoming transport request profile.
3. Tuning parameters that tune the operation of the kernels functions
4. Statistics parameters that control how key statistics are captured
5. Logging parameters that control kernel log handlers
6. Web Proxy parameters that set up the host JVM web proxy

Paths

The following paths may be absolute or relative. If relative they are resolved against the NetKernel basepath.

field	description
scratchDir	Relative URI Scratch - single location of the scratch override directory
deployedModules	Relative URI of document containing list of modules to deploy
expandedJarPool	Relative URI Directory to expand JAR /lib directories of Modules to
modules	Relative URI Directory to store new or downloaded modules in
initURI/initModule	Specifies an initialisation request that will be made upon every startup of the kernel. The initURI will be requested on the initModule and the result discarded. This init process is useful for performing initialisation of the system modules in NetKernel Standard Edition. The default configuration calls a generic startup script in ext_kernel.

Throttle

The throttle sits between transports accepting external requests and the kernel. Its limits the concurrent load that can be placed on the Kernel. By managing the number of requests, memory usage cannot grow unbounded and the stability of the system is guaranteed. Performance will degrade linearly with load once CPU usage reaches 100%.

The throttle guarantees in-order execution of requests.

Suggested performance tuning should be to either:

1. choose the size of the JVM heap using the JVM -Xmx option based available system memory and then to load the system using a worst case scenario and see how many concurrent requests it can handle before running out of memory. Then set the throttle to somewhere below this value.
2. choose what your expected peak load and response times will be and then set the throttle to cope. Increase JVM memory to cope with the loading. Monitoring can done by watching the system summary view or using a performance tuning tool like Sitraka Jprobe.

throttleQueue specifies an upper bound on the number of requests that the throttle will queue before rejecting requests. This value stops the throttle queue from growing unbounded if demand on the server remains high over a sustained period and is therefore useful at helping to manage any denial of service (DoS) attacks.

The Throttle Monitor may be used to monitor dynamic throttle behaviour which gives a guide to service levels experienced by clients. See the Scalability paper for the a demonstration of the throttle behaviour.

Tuning

schedulerThreads

The scheduler manages a pool of threads which perform chunks of work on requests. Therefore the number of threads does not need to be as large as the number of requests if all requests are made asynchronously. In order to efficiently use a multiprocessor system you will need at least as many scheduler threads as processors. Because most requests make use of synchronous requests internally you will usually need 2xThrottle number of scheduler threads. The scheduler will increase threads if it detects starvation due to blocked threads or deadlock.

requestMappingCacheSize

This is an internal cache that optimises request mapping in the module manager. The default value gives a balance between memory usage and performance. The more varied the diet of the kernel the larger this value may need to be. The system will work fine with no caching but performance will be marginally reduced.

houseKeepingPeriod

This is the number of milliseconds that all system components are polled to update their statistics and perform any housekeeping.

deadlockPeriod

The scheduler deadlock detector will flag a session as being deadlocked if it hasn't made a sub-request within this period of time. It will first attempt to increase the thread count to see if deadlock was caused by starvation. If this fails it will issue a failed "deadlock" response on behalf of the blocked request. This will then usually resolve the deadlock by releasing locks and will signal the problem. Deadlocks of this sort indicate programmatic errors and should be investigated.

defaultResourceExpiry

During development it is useful for externally modified files to be detected in realtime. Setting this value low will allow changes in files to be detected quickly at the expense of constant rechecking. We recommend to set this value high on a deployed system where files do not change or are changed through the NetKernel itself and not externally. One of the main effects of having a low value is that any resources that do not otherwise provide validity meta-data, when served over HTTP will inherit the system default expiry period.

defaultCacheModule

This optional element defines a module URI that will be used to provide a cache implementation if no other cache is found in a module related to a request.

For more details on the cache resolution process see the Cache Development Guide.

Statistics

The kernel captures realtime statistics for the following parameters:

• Accessors executed
• Transreptors executed
• JVM heap memory
• Work throughput of transports
• Throttle state

These statistics are captured periodically and are stored in a historical rolling window.

statistics/frequencyDivisor

This integer value is the number of housekeeping periods between generating new statistical snapshots.

statistics/historySize

The number of historical samples that are kept.

statistics/timestampFormat

The timestamp format in the historical samples

Logging Handlers

Kernel logging is reserved for kernel operations and the operations of low-level system modules. Applications should implement their own logging strategies (see application-log).

Kernel Logging can be configured in two dimensions. Who receives the logging messages and which logging events are dispatched. Handlers can be added which receive the events these must implement java.util.logging.Handler interface. These can be optionally formatted using a formatter class implementing java.util.logging.Formatter . By default two Handlers are enabled. One which sends messages to the console and one which writes messages into a log file used by the log viewer.

The configuration of loggers consists of a series of handlers followed by a definition of which levels are logged. Each handler defines a handler instance and an optional formatter, this defaults to java.util.logging.XMLFormatter. Each instance must define a class and, if the instance takes arguments in it's constructor, then a sequence of values which define the constructor. These may be of types string, int, long, and boolean.

Chainsaw

Apache Chainsaw is a graphical log viewer which can be configured to monitor multiple logs. This section describes how to configure chainsaw and netkernel to interoperate.

First configure NetKernel to add a log handler to send events to a socket. Add this XML fragment into the <log> section:

Then configure chainsaw to listen and handle the JDK logging events:

Web Proxy

Web Proxy type, host and port can be specified. This is useful if NetKernel is running behind a non-transparent web proxy and requires access to resources outside the firewall.