Release 9.0
Part Number A92102-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle9iAS Reports Services Publishing Reports to the Web Release 9.0 Part Number A92102-01 |
|
Oracle9iAS Reports Services offers a number of fine-tuning options to adjust the level of service and performance it provides. This chapter discusses tuning considerations and offers you ways to optimize your server environment to fit the needs of your user base. It includes the following topics:
The in-process server is a component of Oracle9iAS Reports Services that resides within the Reports Servlet (rwservlet). It requires less maintenance than a stand-alone server because, unlike the stand-alone server, it starts automatically whenever it receives the first request from the client via the Reports Servlet or JSP-based report URL. Additionally, an in-process server cuts down on the communication between processes, increasing the potential for faster performance.
To indicate that you want to run the Reports Server within the same process as the Reports Servlet, use the SERVER_IN_PROCESS parameter in the Reports Servlet configuration file (rwservlet.properties).
It takes the following syntax:
SERVER_IN_PROCESS=yes
Enter no (the default value) if you do not want the Reports Server to run within the same process as the Reports Servlet.
The Reports Servlet configuration file is located in the following path on both Windows and UNIX:
ORACLE_HOME\reports\conf\rwservlet.properties
The Reports Engine has a number of configuration parameters that relate to performance tuning, including:
These parameters are attributes of the engine element in the Reports Server configuration file, <server_name>.conf, located in the following path on both Windows and UNIX:
ORACLE_HOME\reports\conf\<server_name>.conf
|
Note: You'll find detailed information about the Reports Server configuration file in Chapter 3, "Configuring Oracle9iAS Reports Services". |
The engine element takes the following syntax:
<engine id="rwEng" class="oracle.reports.engine.EngineImpl" initEngine="1" maxEngine="5" minEngine="1" engLife="50" maxIdle="15" callbackTimeOut="10000"><property name="sourceDir" value="D:\orawin\reports\server\cache"/> <property name="tempDir" value="D:\orawin\reports\server\temp"/></engine>
In the following subsections, each of the relevant attributes of the engine element is discussed separately. But another part of this story is how they work together. For example, the initEngine attribute works together with maxEngine and minEngine to set the number of Reports Engines that are always available to users, provided the server is up. These are also affected by engLife, which specifies how many jobs an engine will process before it shuts down. Additionally, to prevent engines from starting up then shutting down in high-volume situations, you may try setting a relatively high value for engLife.
Finally, there is no optimal setting for any of these attributes--the best settings differ based on factors such as how heavy your request load is and whether the request load is constant or fluctuates throughout the day.
The following subsections examine the benefits of high and low attribute values in conjunction with constant and variable request loads and how response time may be affected.
The initEngine attribute defines the number of engines you want the Reports Server to start at initialization. Its default value is 1. The initEngine attribute is influential only when the server first comes up.
Within the Reports Server configuration file, initEngine takes the following syntax:
initEngine="1"
The more engines you initialize at server startup, the longer the Reports Server takes to start and the more memory it requires to sustain them. Higher numbers of user requests coupled with a constant request load will likely benefit from a higher initEngine value. The benefit to be gained from having engines at the ready should outweigh the potential disadvantage of higher memory use. On the other hand, if an engine is not available when a request comes in, time to start up the engine is added to the response overhead.
The maxEngine attribute specifies the maximum number of a given type of engine that can run on the server at the same time. If the number of requests exceeds the number specified for maxEngine, the spillover requests are sent to the Reports Queue and are run as engines become available. The default value is 1.
Within the Reports Server configuration file, maxEngine takes the following syntax:
maxEngine="4"
The minEngine attribute specifies the minimum number of a given type of engine that should be kept running in spite of the maxIdle value (which would otherwise tell an engine to shut down after x number of idle minutes). The default value is 0.
Within the Reports Server configuration file, minEngine takes the following syntax:
minEngine="0"
In an environment with a low request volume or a high tolerance in the user base for less-than-optimal response times, the default value is a good way of preserving memory (by not tying it up with unnecessary engines). In a high request volume environment, where the request load is constant, a higher value should yield quicker response. This is because engines that are already running when requests come in save engine startup time.
The engLife attribute specifies the number of jobs an engine can run before the engine is terminated, and, if necessary, a new engine is started. This feature is available to clean up memory structures. The default value is 50.
Within the Reports Server configuration file, engLife takes the following syntax:
engLife="120"
A low value shuts engines down sooner and consequently frees up memory. In this way, it also allows resources to be recycled. A high value keeps the engine alive for a longer period. This could be valuable in environments that sustain a high-volume of requests throughout the day and where memory use is of lesser concern.
The maxIdle attribute specifies the number of minutes of allowable idle time before an engine is shut down, provided the current number of engines is higher than the value specified for minEngine.
For example, if minEngine is 0, maxIdle is 30, and one engine has been running but unused for 30 minutes, that engine will shut down.
The default value is 30 (minutes).
Within the Reports Server configuration file, maxIdle takes the following syntax:
maxIdle="30"
When you specify this value, you must balance your desire to save engine startup time against your desire to prevent unnecessary use of memory (by idle engines).
The callBackTimeOut attribute specifies the number of milliseconds of allowable waiting time between when the server calls an engine and the engine calls the server back. The default value is 60000 (milliseconds). If the callBackTimeOut value is exceeded before communication is established, an exception is raised, an error message is displayed, and the process is stopped.
Within the Reports Server configuration file, callBackTimeOut takes the following syntax:
callBackTimeOut="60000"
If the server host machine is very fast, you can reduce this number. If it is very slow, you may want to keep this number high to ensure there is sufficient time for the server and the engine to communicate. This value is dependent more on the capabilities of your hardware than on the requirements of your user base.
A cluster is a virtual grouping of servers into a community for the purpose of sharing request processing efficiently across members of the cluster. Clustering in Oracle9iAS Reports Services is peer-level, rather than master/slave. Peer-level clustering means that all members of the cluster take equal responsibility for sharing and processing incoming requests. If one member is shut down, the other members carry on managing the request load. There is no single-point-of-failure, where one machine's malfunction brings the whole system down.
The advantages of clustering are the increased processing power through the pooling of multiple CPUs on multiple machines, the fail-safe environment, and faster response times through request sharing.
Each cluster member machine must be configured in more or less the same way to allow a report to run on each server member in the same way. This means that configuration files should have most of the same settings: a distinction can be drawn between job-related settings and machine-related settings. Job-related settings must be the same from cluster member to cluster member. Job-related settings include settings related to security, data sources, and destination types. Machine-related settings include such attributes as maxEngine, minEngine, maxIdle, initEngine, and the like--these can be different from member to member.
Additionally, for cluster members:
If you must set your servers up for different languages, you won't want to cluster them together. Additionally, if your machines require different job-related configuration settings, you will not benefit from clustering.
For servers to be members of the same cluster, they must share a cluster name (appended to each server's server name) and have the same public and private keys.
|
Note: You'll find more information about enrolling a server in a cluster in Chapter 3, "Configuring Oracle9iAS Reports Services". |
A cache is a temporary storage space for recently accessed data that can return data more rapidly than the data's original storage space. When data is fetched from cache, it saves time otherwise required to arrive at and search the original storage space, and it spares the network the burden of additional traffic.
In Oracle9iAS Reports Services you have three opportunities for getting the most out of your cache:
These opportunities are discussed in the following subsections:
The Reports Server configuration file (ORACLE_HOME\reports\conf\<server_name>.conf) contains a cache element for specifying the Java class that defines the server's cache as well as the cache size and location.
When you use the default Java class provided with the Reports Server, the cache element's syntax is:
<cache class="oracle.reports.cache.RWCache"><property name="cacheSize" value="50"/> <property name="cacheDir" value="ORACLE_HOME\reports\server\cache"/></cache>
Working in conjunction with the TOLERANCE and EXPIRATION command line options, the Reports Server cache speeds report request response times by storing the latest report results and serving them up to subsequent matching requests. Response is faster because a completed report can be fetched from the cache faster than fresh data can be fetched from the database and the display version of the report can be assembled.
The property relevant to tuning is cacheSize. For this value, you enter the number of megabytes of disk space you wish to dedicate to the Reports cache. The default value is 50 (megabytes).
The disk space set aside for cache is available only for caching and cannot be used for any other purpose. The Reports Server keeps track of and protects this space. Outside of restrictions that may have been imposed on a report via the EXPIRATION command, the Reports cache operates on a first-in-first-out principle (FIFO), where, when the cache is full, the oldest data in the cache is overwritten by incoming data.
Higher values allow for storage of more data, but might take longer to search. Lower values provide faster cache hits, but may not be adequate for the amount of data you want to keep on hand, so more duplicate requests are run. Another consideration is the amount of disk space you can reasonably remove from general use. The value you specify for cacheSize should balance these considerations and provide you with the optimal result for your hardware resources and the requirements of your user base.
Oracle9iAS Reports Services provides two command line options for defining how long a particular report that is stored in cache can be used for similar requests (TOLERANCE) and how long a report can remain in cache before it is deleted (EXPIRATION). TOLERANCE and EXPIRATION are essential for effective use of cache because, if they are not defined, your opportunities for reusing cached report results is significantly diminished.
Use TOLERANCE to set the maximum acceptable time for reusing a report's cached output when a duplicate job is detected. Setting the time tolerance on a report reduces the processing time when duplicate jobs are found.
You can use TOLERANCE with the rwclient, rwservlet, and rwcgi commands.
If TOLERANCE is not specified, then Oracle9iAS Reports Services reruns the report even if a duplicate report is found in the cache.
If a report is being processed (that is, it's in the current job queue) when an identical job is submitted, then Oracle9iAS Reports Services reuses the output of the currently running job even if TOLERANCE is not specified or is set to zero.
The syntax of the TOLERANCE command is:
TOLERANCE=[number {unit}] or [{Mon DD, YYYY} hh:mi:ss AM/PM {timezone}]
Number can be any whole value from 0 up. Unit can be minute(s), hour(s), or day(s). The default unit is minute(s). Date is optional. If the date is not specified, today's date is assumed. Timezone is also optional. If the time zone is not specified, the Report Server's time zone is assumed.
Use EXPIRATION to define how long the report output can exist in cache before it is deleted.
You can use EXPIRATION with the rwclient, rwservlet, and rwcgi commands.
If a report is in the current job queue when an identical job is submitted, then the server reuses the output of the currently running job even if EXPIRATION is not specified or is set to zero.
The syntax of the EXPIRATION command is:
EXPIRATION=[number {unit}] or [{Month DD, YYYY} hh:mi:ss am/pm {timezone}]
Number can be any whole value from 0 up. Unit can be minute(s), hour(s), or day(s). The default unit is minute(s). Date is optional. If the date is not specified, today's date is assumed. Timezone is also optional. If the time zone is not specified, the Report Server's time zone is assumed.
The Oracle9iAS Components for Java 2 Enterprise Edition (OC4J) Web Object Cache is a mechanism that allows Web applications written in Java to capture, store, reuse, post-process, and maintain the partial and intermediate results generated by a dynamic Web page, such as a JSP or servlet. For programming interfaces, it provides a tag library (for use in JSPs) and a Java API (for use in servlets).
This section introduces cache-related ojsp tags and points you to documentation that explains how to use these tags, including how to configure your environment to use them.
The Web Object Cache tag library is a convenient wrapper, using JSP custom tag functionality, for the Web Object Cache API. Use custom tags in a JSP to control caching. The API is called through the underlying tag handler classes.
Although we are referring to these tags as "ojsp" tags, which use the ojsp prefix, you can specify any desired prefix in the taglib directive in your JSP file.
You can have one or more of these tags in a given JSP file. The open and close tags surround the data (cache blocks) you want to cache. Multiple cache blocks are distinguished from one another through unique name attributes.
Table 14-1 lists and describes the cache tags available through OC4J.
For detailed information on the OC4J Web Object Cache, see the Oracle Technology Network (http://otn.oracle.com). One useful source is Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference. This includes tag syntax and examples as well as information for configuring your environment to use ojsp:cache tags.
Oracle9iAS Reports Services provide a number of means for monitoring performance that enable you to identify areas that might benefit from additional tuning. The most frequently used means for monitoring server performance include:
SHOWJOBS command line option
Server performance monitoring is discussed in the following subsections:
Oracle Trace is a tool for collecting performance and resource utilization data, such as SQL Parse, Execute, Fetch statistics, and Wait statistics. Whether you are having problems, or simply want to assess server performance for potential tuning opportunities, you can use Oracle Trace to gather information about server performance and use it to inform any decisions you are making concerning your server configuration as well as to inform technical support specialists of recent server activity.
This section provides an overview of Trace, information on the places in Oracle9iAS Reports Services where tracing features are available, and points you to easily accessible sources of additional information.
When you generate a trace file via rwbuilder or rwrun, the resulting trace file contains traces of the whole builder session. Tracing options can be specified from the command line or the Reports Builder configuration file (ORACLE_HOME\reports\conf\rwbuilder.conf).
For example, from the command line, you can specify:
tracefile=trace.trc traceopts=trace_all tracemode=trace_replace
The trace file location is relative to the current working directory or is an absolute location, if specified as such.
In the Reports Builder configuration file, you can specify:
<traceFile="trace.trc" traceOpts="trace_all" traceMode="trace_replace"/>
The trace file location is relative to the server log directory (ORACLE_HOME\reports\logs) or is an absolute location, if specified as such. If the trace file is not specified, the default trace file name is used: <hostname>-rwbuilder.trc in the server logs directory.
Command line tracing options override those specified in the Reports Builder configuration file.
When you generate a trace file for the Reports Server, separate trace files are generated for the Reports Server and the Reports Engine(s). Specify server tracing options in the server configuration file (ORACLE_HOME\reports\conf\<server_name>.conf).
For example:
<trace traceFile="trace.trc" traceOpts="trace_all" traceMode="trace_replace"/>
With a server trace, trace file location is relative to the server logs directory. If a trace file name is not specified, the default server trace file name is used: <server_name>-<engine_name><engine_number>.trc.
With a servlet trace, tracing options can be specified from the rwservlet configuration file (ORACLE_HOME\reports\conf\rwservlet.properties). For example:
TRACEOPTS=TRACE_ALL TRACEFILE=rwservlet.trc TRACEMODE=TRACE_REPLACE
With a servlet trace, trace file location is relative to the server log directory (ORACLE_HOME\reports\logs).
Oracle9iAS Reports Services offers a number of ways to set up a trace and view trace results:
ORACLE_HOME\reports\conf\server_name.conf). This is discussed in Chapter 3, Section 3.2.1.11, "trace".
ORACLE_HOME\reports\conf\rwservlet.properties). This is discussed Section 3.3.5, "Setting up Trace Options for the Reports Servlet and JSPs".
How to define a runtime command line via a URL is discussed in Chapter 8, "Running Report Requests".
Note:
The showjobs command keyword is useful for displaying a Web view of Reports Server queue status. Use it only with the rwservlet command. It uses the following syntax:
Reports_URL/rwservlet/showjobs?server=server_name&statusformat=desired_format
Table 14-2 lists and describes valid values for SHOWJOBS parameters.
SHOWJOBS parameters
When you move to centralized reporting, your user base may require certain operational information. For example:
The Oracle9iAS Reports Server makes it possible to answer both of these questions by posting the current report queue to the database each time a job request is submitted. This information is inserted into a RW_SERVER_QUEUE table that includes the following data:
Table 14-3 lists and describes the information contained in the RW_SERVER_QUEUE table:
| Column Name | Description |
|---|---|
|
JOB_TYPE |
States whether the job listed is CURRENT, PAST, or SCHEDULED. |
|
JOB_ID |
System generated job identification number. |
|
JOB_NAME |
Job submission name (or file name if no value for JOBNAME is specified). |
|
STATUS_CODE |
Current status of job. See Table 14-4, " Job Submission Status Codes" for more information about status codes. |
|
STATUS_MESSAGE |
Full message text relating to status code (includes Oracle9iAS error messages if report is terminated). |
|
COMMAND_LINE |
Complete command line submitted for this job submission. |
|
OWNER |
User who submitted the job. On the Web, the default user is the OS user who owns the Web server. |
|
DESTYPE |
Format of the report output. |
|
DESNAME |
Name of the report output if not going to the Oracle9iAS Reports Server cache. |
|
SERVER |
Oracle9iAS Reports Server to which the report was submitted. |
|
QUEUED |
Date and time the job submission was received and queued by the given Oracle9iAS Reports Server. |
|
STARTED |
Date and time the job submission was run. |
|
FINISHED |
Date and time the submitted job completed. |
|
LAST_RUN |
Date and time a scheduled job was last run. |
|
NEXT_RUN |
Date and time a scheduled job will run. |
|
REPEAT_INTERVAL |
Frequency on which to run a job. |
|
REPEAT_PATTERN |
Repeat pattern (for example, every minute, every hour, or every day). |
|
CACHE_HIT |
Indicates whether the job result was fetched from cache instead of running itself. |
|
CACHE_KEY |
Indicates the cache key used to compare a request with an already cached result. The key is a string that uniquely indicates a report output result without considering the time the job was run. For example, if two requests have the same key, it means they will both generate the same output if they are running at the same time, although the outputs may be used for different purposes (e.g., send to e-mail or save to a file). |
Users can view this table if you grant them SELECT access. This will enable them to query the job submission of interest and determine the job's current status. You can also give them a view of this data by implementing an Oracle9iAS Reports Server Queue screen. You can implement such a screen by creating a report based directly on this table. Doing so displays the queue report as a job submission by the user.
Conversely, the real-time update of the table with the status of job submissions makes it very easy for administrators to know exactly how many concurrent users have requested jobs to be run on the Reports Server.
By counting the number of entries in the RW_SERVER_QUEUE table that have a status code indicating that the job has been queued but not completed, it is possible to return an accurate number of the current active users on the server. For example, you could use the following query:
SELECT Count(*) FROM RW_SERVER_QUEUE WHERE STATUS_CODE IN (1, -- ENQUEUED 2, -- OPENING 3) -- RUNNING AND JOB_TYPE != 'Scheduled'
The Reports Server job queue is implemented through the use of a PL/SQL case API. It functions to update the queue table with the queue information as requests are made. This implementation is defined in the following path:
ORACLE_HOME\reports\admin\sql\RW_SERVER.SQL
To implement the queue, take the following required steps:
rw_server.sql file to a database (this file is included with your Oracle9iAS Reports Services installation: ORACLE_HOME\reports\admin\sql).
This creates a schema that owns the report queue information and has execute privileges on the server queue API.
ORACLE_HOME\reports\conf\server_name.conf) to the connection string of the schema that owns the queue data.
When the server starts, it connects as the defined user and logs job submissions.
|
 Copyright © 2002 Oracle Corporation. All Rights Reserved. |
|