|
NetKernel Configuration Guide |
Important Notice
Many of the system configuration options can now be changed at runtime using the system configuration tool.This document describes the various configuration and tuning options available for the 1060 NetKernel and some important standard components
NetKernel Configuration
The 1060kernel.jar file contains a configuration file
/system.xml which defines how the kernel is configured.
This can be overriden by placing another configuration file in the main JVM classpath
before the 1060netkernel.jar. The salisbury distribution uses this approach
with a classpath entry for system.xml in the <install>/etc directory.
Throttle
The throttle sits between transports accepting external requests and
the kernel. Its limits the concurrent load that can be placed on the Kernel since too
much load doesn't only cause an inevitable slowdown it also causes a
larger working set of memory. If left unbounded a heavily loaded server
will run out of memory and rapidly become unstable. By limiting the
number of requests such that memory usage will not grow unbounded the
stability of the system is preserved and 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:
- 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.
- 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.
schedulerThreads
The scheduler doesn't use a thread-per-request approach to processing. Instead it manages a pool of threads which perform chunks of work on requests. Therefore the number of threads doesn't need to be as large as the number of requests if all requests are made asynchronously- synchronous requests causes the requesting thread to be blocked. 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- DPML for example 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 no caching but just be a bit slower.
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. Setting this value low will allow changes in files to be detected at the expense of constant rechecking. Set this value high on a deployed system where files do not change or are changed through the NetKernel itself and not externally. A low value is similar to not having a cache but will yield better performance as resources are only re-evaluated if they are changed. One of the main effects of having a low value is that any served resources over HTTP will not have a very long validity period.
initURI
initURI and initModule specify an init process that
will be called upon every startup. The default configuration calls a generic
startup script in ext_kernel.
statistics/frequencyDivisor
This integer value is the number of housekeeping periods between generating new statistical snapshots for memory and workload.
statistics/historySize
The number of historical samples that are kept.
statistics/timestampFormat
The timestamp format in the historical samples
Kernel Logging Handlers
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 .
Default Config
<!-- ************************************************************ Resource Locations NB All paths are resolved with respect to the <install> basepath. eg /scratch uses <install>/scratch ************************************************************ -->
<!-- ********** Scratch - single location of the scratch override directory ********** -->
<scratchDir>/scratch</scratchDir>
<!-- ********** Directory to expand Jar /lib directories of Modules to ********** -->
<expandedJarPool>/lib/expanded</expandedJarPool>
<!-- ************************************************************ Kernel Settings ************************************************************ -->
<!-- ********** Maximum number of concurrent requests allowed to enter Kernel from the Transports. ********** -->
<throttle>5</throttle>
<!-- ********** Maximum number of requests queued before requests are rejected by throttle. ********** -->
<throttleQueue>10</throttleQueue>
<!-- ********** Number of Scheduler Threads to start with. Number grows if blocking requests are made. Kernel manages the number of additional threads above this baseline on a demand basis. ********** -->
<schedulerThreads>2</schedulerThreads>
<!-- ********** Number of lines of the exception stack to serialize to the XML Exception document ********** -->
<exceptionStackDepth>4</exceptionStackDepth>
<!-- ********** The URI of the module containing a cache to use as default if none is specified in a specific module ********** -->
<defaultCacheModule>urn:org:ten60:netkernel:cache:standard</defaultCacheModule>
<!-- ********** The size of the cache kept by the scheduler of requests resolved to accessors ********** -->
<requestMappingCacheSize>512</requestMappingCacheSize>
<!-- ********** HouseKeeping Thread execution period in milliseconds ********** -->
<houseKeepingPeriod>500</houseKeepingPeriod>
<!-- ********** Period of inactivity within a session after which deadlock is assumed. Deadlock resolution process includes increasing available threads and issuing an interrupted response. ********** -->
<deadlockPeriod>30000</deadlockPeriod>
<!-- ********** Interval for which an ffcpl: resource is assumed to be valid and will not be rechecked for freshness. Set low for easy development and high for maximum performance in deployment ********** -->
<defaultResourceExpiry>1000</defaultResourceExpiry>
<!-- ********** This URI is requested by the kernel after sucessful startup ********** -->
<initURI>active:init</initURI>
<initModule>urn:org:ten60:netkernel:ext:kernel</initModule>
<!-- ************************************************************ Kernel Statistics Settings ************************************************************ -->
<statistics>
<!-- ********** Number of times Housekeeper must run before a sample is taken ********** -->
<frequencyDivisor>10</frequencyDivisor>
<!-- ********** Number of statistic samples to store ********** -->
<historySize>60</historySize>
<!-- ********** Format for statistic time stamp ********** -->
<timestampFormat>HH:mm:ss</timestampFormat>
</statistics>
<!-- ************************************************************ Kernel Logger Settings ************************************************************ -->
<log>
<!-- ********** Logging Handler - as many as required ********** -->
<handler>
<handlerClass>java.util.logging.ConsoleHandler</handlerClass>
<formatterClass>com.ten60.netkernel.util.ConsoleFormatter</formatterClass>
</handler>
<!-- ********** Log level settings - values can be: debug, fine, info, warning, severe, application, container ********** -->
<level>
<warning />
<severe />
<application />
<container />
</level>
</log>
</system>
Deployed Modules
A /deployedModules.xml file is loaded from the install path at startup.
This contains a list of modules that will be deployed. This file can be edited manually
or via the netkernel:module-list URI provided
by the system component accessor in ext_kernel.
Cache Configuration
Caches may be imported for each module, in general however a single cache for all modules imported in the application fulcrum is the most common configuration.
The standard_cache module provides a smart cache DependencyCostCache which takes some configuration options.
The configuration is read from ffcpl:/etc/CacheDependencyCostConfig.xml, which should be located in the
module that hosts the cache.
<!-- ********* Cache Size Total number of cached resources ********* -->
<cacheSize>200</cacheSize>
<!-- ********* Prune Size Number of cached resources to remove in a cache prune cycle ********* -->
<pruneSize>40</pruneSize>
<!-- ********* Memory Threshold Maximum baseline memory size above which cache pruning is forced. Expressed as %age. ********* -->
<memoryThreshold>66</memoryThreshold>
<!-- ********* Puts Threshold Number of additional PUTS after a prune cycle before memory testing is resumed ********* -->
<putsThreshold>20</putsThreshold>
</config>
This cache configuration will attempt to keep a float of 200 resources upto a limit of occupying 66% of available JVM heap space. Actuall memory may be monitored in real time using the Memory Monitor. Applications which require a large amount of working memory may operate more efficiently if the memory consumption of the cache is further limited.
Transport Configuration
Like the cache config, transport configuration is specified in the module that imports a transport.
The Jetty HTTP transport configuration is specified at ffcpl:/etc/TransportJettyConfig.xml, it is
discussed in depth here.
|
1060® NetKernelTM Documentation (C) 2003-2004 1060 Research Limited Send Feedback |