Administrator's Guide

Chapter 9 Tuning the Server

This chapter describes how the SilverStream Server connects with the client and the database. It also describes how you can use the SilverStream Management Console (SMC) to set server connection parameters and server cache parameters in order to improve the overall performance and efficient operation of your system.

This chapter contains sections on:

Managing database connections

This section contains the following topics:

For information about the SilverStream data access architecture, including its data cache objects, see the data access chapter in the Programmer's Guide.

About database connections and performance

The SilverStream Server handles all connections between a SilverStream client and a database. Each database connection is typically a TCP/IP connection, established between the SilverStream Server and the database server through JDBC.

Most database servers place a limit on the number of database connections that can be open simultaneously. You can use the SMC to set the minimum (initial) and maximum number of connections used by the Silverstream Server for each database.

The maximum number of open SilverStream database connections you set will normally equal the maximum number of users who will be simultaneously querying or updating the database.

Exception

Complicated forms might require more than one database connection, so the number of connections might exceed the number of users.

Determining the correct maximum number of connections

Setting a maximum that is too small will result in degraded performance: If a client attempts to access the database when all connections are in use, the client will be blocked until an in-progress query or update is completed. You might want to experiment with different maximum settings to optimize your server performance.

If other database users will be establishing connections to the database server independently of SilverStream, you might need to reduce the maximum number of open SilverStream connections. This ensures that database connections are available for non-SilverStream users.

You should consult your DBMS documentation and ensure that your database has been configured to accept the number of client connections specified in the SMC, taking into account other applications that might be accessing the database.

Setting the maximum and minimum number of database connections

You can set the default maximum and minimum number of database connections as well as the number of connections for specific databases. You do this on the Databases panel in the SMC.

Setting the default number of connections

You can set the default minimum and maximum number of database connections.

These values are used by:

Subsequently added databases.
All databases that are currently on the server that are using the default minimum or maximum number of connections (that is, databases whose minimum or maximum number of connections have not been changed from the default).

NOTE To override the defaults for a specific database, see Setting the number of connections for a specific database.

To set the default maximum and minimum number of database connections:

Invoke the SMC.
Select Configuration options.
Select the Databases panel.

Edit the fields at the top of the panel as needed.

Field

Description

Minimum number of database connections

The default minimum number of connections for a database. The SilverStream Server will immediately establish this many connections when it is started, and keep them open as long as the server is running.

NOTE If the database crashes, then restarts, SilverStream will drop the old connections and reestablish new ones as needed. It will not immediately establish what had been specified as the minimum number of connections.

Maximum number of database connections

The default maximum number of connections for a database. The Silverstream Server will open connections on demand up to this number.

Make sure that the maximum number of open SilverStream connections is less than or equal to the total number allowed by the database server; otherwise the SilverStream Server will get errors from the database server when it attempts to open a connection.

For more information, see About database connections and performance.

Click Update.
To activate the new settings, click the Restart button.

Field	Description
Minimum number of database connections	The default minimum number of connections for a database. The SilverStream Server will immediately establish this many connections when it is started, and keep them open as long as the server is running. NOTE If the database crashes, then restarts, SilverStream will drop the old connections and reestablish new ones as needed. It will not immediately establish what had been specified as the minimum number of connections.
Maximum number of database connections	The default maximum number of connections for a database. The Silverstream Server will open connections on demand up to this number. Make sure that the maximum number of open SilverStream connections is less than or equal to the total number allowed by the database server; otherwise the SilverStream Server will get errors from the database server when it attempts to open a connection. For more information, see About database connections and performance.

Resetting the defaults

You can reset the default minimum and maximum number of connections. This applies to all databases on the server.

To reset the defaults:

Click Reset all next to Minimum or Maximum number of connections at the top of the Databases panel.

The default minimum or maximum number of connections is reset, and all the databases on the server are reset to use the newly set default for minimum or maximum number of connections.

Setting the number of connections for a specific database

You can override the default numbers of database connections for a specific database.

To override the default minimum/maximum connections for a specific database:

Invoke the SMC.
Select Configuration options.
Select the Databases panel.
Select the database you want to configure from the list box.

Set the minimum and maximum number of database connections for the selected database by editing the fields below the database name.

Field

Description

Minimum number of database connections

The SilverStream Server will immediately establish this many connections when it is started, and keep them open as long as the server is running. Setting a value here overrides the default value.

NOTE If the database crashes, then restarts, SilverStream will drop the old connections and reestablish new ones as needed. It will not immediately establish what had been specified as the minimum number of connections.

Maximum number of database connections

The Silverstream Server will open additional connections on demand up to this number. Setting a value here overrides the default value.

Make sure that the maximum number of open SilverStream connections is less than or equal to the total number allowed by the database server; otherwise the SilverStream Server will get errors from the database server when it attempts to open a connection.

For more information, see About database connections and performance.

Click Update.
To activate the new settings, click the Restart button.

Field	Description
Minimum number of database connections	The SilverStream Server will immediately establish this many connections when it is started, and keep them open as long as the server is running. Setting a value here overrides the default value. NOTE If the database crashes, then restarts, SilverStream will drop the old connections and reestablish new ones as needed. It will not immediately establish what had been specified as the minimum number of connections.
Maximum number of database connections	The Silverstream Server will open additional connections on demand up to this number. Setting a value here overrides the default value. Make sure that the maximum number of open SilverStream connections is less than or equal to the total number allowed by the database server; otherwise the SilverStream Server will get errors from the database server when it attempts to open a connection. For more information, see About database connections and performance.

Restoring the values to the defaults

You can reset the minimum or maximum number of connections for a specific database to be the default values.

To restore minimum/maximum connections to the defaults:

Select the database you want to configure from the list box.
Click Reset next to Minimum or Maximum number of connections for the selected database.

The minimum or maximum number of connections is reset to be the default value (which is shown at the top of the panel).

Using prefetch buffers

SilverStream uses prefetch buffers to speed up database operations. A prefetch buffer is initiated by a database query from a SilverStream form or view. When a table is returned and displayed in a form or view, the rows are visible to the user one screen at a time. However the server will fetch more than one screenful of rows and store them in the prefetch buffer, in anticipation of the user wanting to view the entire set.

NOTE Prefetch buffers are not used with pages (except when a Java form or view is included on the page) or with business objects.

Important note about prefetch buffers

Prefetch buffers are temporary; they do not hold data until it is requested. Unless the creator of the form or view specified the Limit number of returned rows feature, all the rows resulting from the query will go to the client, even if there are millions of rows. As soon as the client asks for any data, it will eventually get all of it. (This is true also with pages; all the data will eventually go to the client unless the user cancels the operation.)

For more information about the Limit number of returned rows feature, see the Form Designer, Page Designer, or View Designer in the online Tools Guide.

How prefetch buffers are managed

The following diagram and description illustrate how SilverStream manages prefetch buffers.

At the start of a client query, SilverStream allocates a prefetch buffer that fetches 150 rows from the database. The following describes a generic sequence.

Using the client interface, the user does gotoFirst() on the client AgData.
A background thread starts on the client, requesting 100 rows from the server.
100 rows are moved from the prefetch buffer to the communication line. A prefetch thread gets 100 more rows from the database.
Eventually the client thread gets the last row from the prefetch buffer, which frees the prefetch thread.

You can set the number of prefetch buffers for a server. Typically, you want to allocate one prefetch per user (matching the number of client connections). You might see a performance improvement if you set the number higher than the default. Before you do so, make sure that you have the server capacity (that is, enough memory) to handle the additional memory overhead of the additional prefetch buffers.

Here is a guideline for calculating how much memory a prefetch buffer might consume:

  Average row size in byes * 150 rows

where Average row size is the sum of the sizes of each of the columns being accessed by an AgData in your application.

Setting performance parameters

To improve performance, you can use the SMC to set the number of prefetch buffers, as well as other connection parameters.

To set performance parameters:

Invoke the SMC.
Select Configuration options.
Select the Advanced panel.
Select the Performance tab.

Edit the settings as needed.

Field

Description

Number of prefetch buffers

The total number of prefetch buffers to use with this server. See Using prefetch buffers.

Timeout on server request

The maximum total server-side time for processing a client request, from the instant the request is received until the reply is sent back. This allows the server to time-out in the event of a persistent problem.

You should set this value to be substantially longer than the longest expected server response time.

Session timeout

The time after which the server will terminate a session with a client after the client goes idle. The default value is five minutes. The SilverStream Designer, SilverJRunner, and Java forms running in the browser "ping" the server every four minutes to keep their session alive.

You probably don't want to reduce this value below four minutes, as it might interfere with the Designer, SilverJRunner, and Java form pinging, resulting in the server dropping active connections.

The session timeout value affects how long session object variables are maintained. The longer the timeout, the longer the memory used for a session will be consumed by the server. In deployed applications that do not use session objects, you probably want to use a short session timeout.

Buffering reply size

The size of the packet (in bytes) in which larger replies are gathered, copied, and sent back to the client.

Setting this to a larger size might provide better performance, but limit the size to 8KB or 16KB, depending on available server physical memory and the number of client connections.

Click Update.
To activate the new setting(s), click the Restart (server) button.

Field	Description
Number of prefetch buffers	The total number of prefetch buffers to use with this server. See Using prefetch buffers.
Timeout on server request	The maximum total server-side time for processing a client request, from the instant the request is received until the reply is sent back. This allows the server to time-out in the event of a persistent problem. You should set this value to be substantially longer than the longest expected server response time.
Session timeout	The time after which the server will terminate a session with a client after the client goes idle. The default value is five minutes. The SilverStream Designer, SilverJRunner, and Java forms running in the browser "ping" the server every four minutes to keep their session alive. You probably don't want to reduce this value below four minutes, as it might interfere with the Designer, SilverJRunner, and Java form pinging, resulting in the server dropping active connections. The session timeout value affects how long session object variables are maintained. The longer the timeout, the longer the memory used for a session will be consumed by the server. In deployed applications that do not use session objects, you probably want to use a short session timeout.
Buffering reply size	The size of the packet (in bytes) in which larger replies are gathered, copied, and sent back to the client. Setting this to a larger size might provide better performance, but limit the size to 8KB or 16KB, depending on available server physical memory and the number of client connections.

Managing client connections

This section describes how a client connection is established on the server, and how you can modify connection parameters to improve performance.

NOTE Client connections are not the same as database connections. The latter are described in Managing database connections.

Client sessions and threads

When a client first connects with the server through HTTP, the server establishes the connection by allocating a thread (if available) from the connection pool. The thread is a lightweight background process that does the following:

Creates a server session
Executes the HTTP request by hooking up to the appropriate server components and passing the result back to the client

About threads

The thread is associated with the client connection until either the client or the server closes it. The server will close the connection according to the settable connection parameters. When the connection is closed, the thread is returned to the connection pool.

About session objects

The session is an object on the server that does the following:

Stores information about the client (such as user ID, login, and host name).
Stores the application data included programmatically in the client's session object (such as in a shopping cart application, which needs to store purchases and other information for each client along the way).
Remains alive for a specified time (session timeout period) after all threads have been returned to the pool. (In certain cases there can be more than one client thread associated with a session.) This allows the client to reconnect to the session within the specified time. The default timeout is five minutes. Once a session object has been deleted by the server, its contents are gone.

The following diagram shows a client connection with the server session and its associated thread.

Client connection parameters

The SilverStream Server imposes a limit on the total number of allowable client connections (threads). Within this allowance, you can modify connection parameters in order to manage the server load in your production environment. The server defines client connections in terms of individual connection states and overall loads:

Connection states

Each client connection (thread) exists in one of the following states:

Free, if it is not in use
Active, if it is connected, in use, and a request is in progress
Idle, if it is connected and in use, but no request is in progress on the connection

Once a thread has been idle for the session timeout period, SilverStream closes the connection and returns the thread to the connection pool. (You can configure the timeout period. See Setting performance parameters.)

A thread typically has the following lifecycle:

Load levels

The Server has two load levels: light and busy. It behaves differently when requests for new connections are made, depending on whether its load is light or busy.

How the SilverStream Server operates based on load levels

Here is what happens when the server receives a request for a new connection:

A request is made for a new connection to the server.

SilverStream responds based on its load level.

Load level

What SilverStream does

Light

The new request is allocated a free thread.

When an active connection goes idle, it is kept open until it times out.

Busy

The Server closes older idle connections (enough to bring the server to the light load level if possible), returning the threads to the connection pool, then allocates a free thread to the new request.

If there are no idle connections (that is, all the allowable number of connections are active), the new request is refused.

Load level	What SilverStream does
Light	The new request is allocated a free thread. When an active connection goes idle, it is kept open until it times out.
Busy	The Server closes older idle connections (enough to bring the server to the light load level if possible), returning the threads to the connection pool, then allocates a free thread to the new request. If there are no idle connections (that is, all the allowable number of connections are active), the new request is refused.

Specifying how the load level is determined

You can specify how the server determines whether the load is light or busy by setting the following properties. In the descriptions that follow, the terms in bold refer to the label for the properties in the SMC and the terms in parentheses are the names of the corresponding properties in the AgiAdmServer interface in the Server Administration API (without the PROP_ prefix).

Maximum number of client connections (MAXCLIENTCONNS). The total number of allowable connections. The default is 20.
Free client connections for "light" (FREECLIENTCONNSLIGHT). Determines whether the server is considered to be light or busy.
- If the number of free connections is less than FREECLIENTCONNSLIGHT, the server is considered to be busy.
- If the number of free connections equals or exceeds FREECLIENTCONNSLIGHT, the server is considered to be light.
  
  The default for FREECLIENTCONNSLIGHT is 10.

NOTE Two other properties--Free client connections for "busy" (FREECLIENTCONNSBUSY) and Idle client connections for "light" (IDLECLIENTCONNSLIGHT)--are used internally and should be set as described in Setting the connection parameters.

Determining an appropriate value for MAXCLIENTCONNS

You should set MAXCLIENTCONNS to the maximum number of connections that will be active simultaneously on your server, plus approximately 10% for peak times. The server creates a separate thread for handling each active connection.

Setting this parameter too high will result in excessive consumption of system resources by your server and setting it too low will result in connections being refused.

A general guideline is to set this parameter to the maximum number of simultaneous sessions you expect your server to serve (plus 10% or so) assuming there will be about one active connection per session (but remember that complicated forms might require more than one connection, so there might be more connections than users).

Determining an appropriate value for FREECLIENTCONNSLIGHT

Typically you will set FREECLIENTCONNSLIGHT low if your application has a stable user load, such as with an intranet application. Setting FREECLIENTCONNSLIGHT low means that the application is usually in a light load so idle connections are maintained longer, allowing existing users to maintain their connections longer.

For Internet applications, where the user load can vary dramatically, you might want to set FREECLIENTCONNSLIGHT relatively high, to better ensure that new users can get a connection. Idle connections are terminated more quickly.

Setting the connection parameters

You can set the connection parameters in the SMC.

To set client connection parameters:

Invoke the SMC.
Select Configuration options.

Select the Connections panel.

Following is a description of each of the fields.

Field

Description

Maximum number of client connections

MAXCLIENTCONNS. Determines the maximum number of connections. Set as described in Determining an appropriate value for MAXCLIENTCONNS.

Free client connections for "busy"

FREECLIENTCONNSBUSY. Used internally. Set to the same value as FREECLIENTCONNSLIGHT.

Free client connections for "light"

FREECLIENTCONNSLIGHT. Determines when the server is considered to be light or busy. Set as described in Determining an appropriate value for FREECLIENTCONNSLIGHT.

Idle client connections for "light"

IDLECLIENTCONNSLIGHT. Used internally. Set to the same value as MAXCLIENTCONNS.

Edit the settings as needed, then click Update.

The new settings take place immediately.

Field	Description
Maximum number of client connections	MAXCLIENTCONNS. Determines the maximum number of connections. Set as described in Determining an appropriate value for MAXCLIENTCONNS.
Free client connections for "busy"	FREECLIENTCONNSBUSY. Used internally. Set to the same value as FREECLIENTCONNSLIGHT.
Free client connections for "light"	FREECLIENTCONNSLIGHT. Determines when the server is considered to be light or busy. Set as described in Determining an appropriate value for FREECLIENTCONNSLIGHT.
Idle client connections for "light"	IDLECLIENTCONNSLIGHT. Used internally. Set to the same value as MAXCLIENTCONNS.

Managing the server content cache

SilverStream uses server-side caching for various purposes, including resource naming and attribute information, database schema information, and prefetch buffering. SilverStream also stores (or caches) the contents of file resources, such as media store objects, in memory or on disk. Caching is mostly invisible to users except that it does affect performance.

The two caches

There are two separate caches for every SilverStream Server:

Memory cache. This cache is held completely in-memory, and is intended for holding smaller files
Disk cache. This cache is on disk, and is intended for larger files.

What you can configure

Each cache has two settings you can configure:

The maximum content size. The maximum size of any individual file allowed into the cache.
The maximum cache size. The maximum size of the cache itself (that is, the total size of all the files in the cache).

You can also specify the directory used for disk caching.

How SilverStream uses the caches

The server uses the most appropriate cache for each file, based on the file's size. Small files are stored in the memory cache and larger files are stored in the disk cache. Very large files are not cached at all. The server uses an LRU (least recently used) algorithm within each cache, throwing out old (not recently used) files when the cache becomes full.

To set cache settings:

Invoke the SMC.
Select Configuration options.
Select the Advanced option.
Select the Cache tab.

The following dialog appears.

Specify the settings as follows.

Field

Description

Content cache enabled

Enables or disables the content cache. If unchecked, all content caching is turned off.

Caching frequently requested file resources will improve the response time for these resources. Turn off only for debugging purposes.

Maximum size of the disk cache

The maximum size of the disk cache, in bytes. The total size of all files in the cache is always less than or equal to this. If set to 0, the disk cache is disabled.

In general, make this cache large enough to store the remainder of frequently used files after you have determined the in-memory cache size (see the description of "Maximum size of the in-memory cache").

Maximum size of any file that will be cached in the disk cache

The maximum size of any file that is cached in the disk cache, in bytes.

Files less than or equal to this size but too large for the in-memory cache are cached in the disk cache. Files greater than this size are not cached.

Maximum size of the in-memory cache

The maximum size of the in-memory cache, in bytes. The total size of all files in the cache is always less than or equal to this. If set to 0, the in-memory cache is effectively disabled.

In general, make this size as large as possible without causing excessive paging activity on your system.

Maximum size of any file that will be cached in the in-memory cache

The maximum size of any file that is cached in the in-memory cache, in bytes. Files less than or equal to this size will be cached in the in-memory cache.

Directory for disk cache entries

The directory in which the disk cache entries are stored. By default, this is a subdirectory of the SilverStream installation directory.

The server tries to create this directory if it doesn't exist. The server also tries to clear out all the cache files from this directory when it starts up. (You might want to have a directory that is dedicated to the cache.)

If the server cannot find or create this directory, the disk cache is disabled.

Click Update.

The new settings take effect immediately.

Field	Description
Content cache enabled	Enables or disables the content cache. If unchecked, all content caching is turned off. Caching frequently requested file resources will improve the response time for these resources. Turn off only for debugging purposes.
Maximum size of the disk cache	The maximum size of the disk cache, in bytes. The total size of all files in the cache is always less than or equal to this. If set to 0, the disk cache is disabled. In general, make this cache large enough to store the remainder of frequently used files after you have determined the in-memory cache size (see the description of "Maximum size of the in-memory cache").
Maximum size of any file that will be cached in the disk cache	The maximum size of any file that is cached in the disk cache, in bytes. Files less than or equal to this size but too large for the in-memory cache are cached in the disk cache. Files greater than this size are not cached.
Maximum size of the in-memory cache	The maximum size of the in-memory cache, in bytes. The total size of all files in the cache is always less than or equal to this. If set to 0, the in-memory cache is effectively disabled. In general, make this size as large as possible without causing excessive paging activity on your system.
Maximum size of any file that will be cached in the in-memory cache	The maximum size of any file that is cached in the in-memory cache, in bytes. Files less than or equal to this size will be cached in the in-memory cache.
Directory for disk cache entries	The directory in which the disk cache entries are stored. By default, this is a subdirectory of the SilverStream installation directory. The server tries to create this directory if it doesn't exist. The server also tries to clear out all the cache files from this directory when it starts up. (You might want to have a directory that is dedicated to the cache.) If the server cannot find or create this directory, the disk cache is disabled.