wfi
System Administration
Table of contents 1. Summary.......................................................................6 2. Overall architecture.......................................................7 2.1. The iKnowBase modules......................................................................................7 2.2. iKnowBase running with Oracle Portal.................................................................8 2.3. iKnowBase running with the page engine............................................................8
3. Monitoring the iKnowBase components..........................9 3.1. Database logging................................................................................................ 9 3.1.1. Error log......................................................................................................... 9 3.1.1. Error log........................................................................................................... 9 3.1.2. Performance log............................................................................................. 9 3.1.2. Performance log............................................................................................... 9 3.1.3. Component execution log..............................................................................9 3.1.3. Component execution log.................................................................................9 3.2. Java application logging.....................................................................................10 3.2.1. Configuring logging......................................................................................10 3.2.1. Configuring logging........................................................................................10 3.2.2. Log levels..................................................................................................... 10 3.2.2. Log levels....................................................................................................... 10 3.2.3. Sample log configuration.............................................................................11 3.2.3. Sample log configuration................................................................................11 3.2.4. Monitoring logging at run time.....................................................................11 3.2.4. Monitoring logging at run time.......................................................................11 3.3. Performance monitoring....................................................................................11 3.4. Metadata cache................................................................................................. 12 3.4.1. Cache clearing and invaliation.....................................................................12 3.4.1. Cache clearing and invaliation........................................................................12 3.4.2. Cache monitoring......................................................................................... 12 3.4.2. Cache monitoring........................................................................................... 12
iKnowBase System Administration
2|Page
3.5. Web application environment entries (web.xml / JNDI)......................................13 3.6. Performance troubleshooting the OC4J-container..............................................13 3.6.1. Thread information.......................................................................................13 3.6.1. Thread information......................................................................................... 13 3.6.2. Garbage collection.......................................................................................13 3.6.2. Garbage collection.......................................................................................... 13 3.6.3. Maxed out CPU............................................................................................. 14 3.6.3. Maxed out CPU............................................................................................... 14
4. Administration console.................................................15 4.1. Main menu......................................................................................................... 15 4.2. Java................................................................................................................... 15 4.2.1. Request........................................................................................................ 15 4.2.1. Request.......................................................................................................... 15 4.2.2. JVM............................................................................................................... 16 4.2.2. JVM................................................................................................................. 16 4.2.3. Threads........................................................................................................ 16 4.2.3. Threads.......................................................................................................... 16 4.2.4. JNDI.............................................................................................................. 17 4.2.4. JNDI................................................................................................................ 17 4.3. Database........................................................................................................... 17 4.4. Cache................................................................................................................ 18 4.5. Logging............................................................................................................. 19 4.5.1. Config........................................................................................................... 19 4.5.1. Config............................................................................................................. 19 4.5.2. Loggers........................................................................................................ 19 4.5.2. Loggers........................................................................................................... 19 4.5.3. Appenders.................................................................................................... 20 4.5.3. Appenders...................................................................................................... 20 4.5.4. Database...................................................................................................... 21 4.5.4. Database........................................................................................................ 21
iKnowBase System Administration
3|Page
4.6. Monitor.............................................................................................................. 22 4.6.1. All................................................................................................................. 22 4.6.1. All................................................................................................................... 22 4.6.2. Page............................................................................................................. 22 4.6.2. Page............................................................................................................... 22
5. Development tools.......................................................24 5.1. Session tracing.................................................................................................. 24
6. Content caching...........................................................26 6.1. Content caching with Oracle Portal...................................................................26 6.1.1. Understanding caching in Oracle Portal.......................................................26 6.1.1. Understanding caching in Oracle Portal..........................................................26 6.1.2. Caching with the iKnowBase Portlets...........................................................27 6.1.2. Caching with the iKnowBase Portlets..............................................................27 6.1.3. iKnowBase, Oracle Portal and WebCache.....................................................27 6.1.3. iKnowBase, Oracle Portal and WebCache.......................................................27 6.1.4. Portlet caching per user rather than per session..........................................28 6.1.4. Portlet caching per user rather than per session............................................28 6.1.5. Disable caching for users other than public.................................................29 6.1.5. Disable caching for users other than public....................................................29 6.1.6. Selecting cache method...............................................................................30 6.1.6. Selecting cache method.................................................................................30 6.1.7. Troubleshooting caching..............................................................................30 6.1.7. Troubleshooting caching................................................................................30 6.1.7.1. Enabling webcache logging.....................................................................30 6.1.7.1. Enabling webcache logging.........................................................................30 6.1.7.2. Enable iKnowBase logging.......................................................................31 6.1.7.2. Enable iKnowBase logging...........................................................................31 6.2. Content caching with the page engine..............................................................32
7. Performance testing using the TestRunner...................33 7.1. Execution........................................................................................................... 33
iKnowBase System Administration
4|Page
7.2. Configuration..................................................................................................... 34 7.2.1. Test suite definition......................................................................................35 7.2.1. Test suite definition........................................................................................35 7.2.2. Test definition.............................................................................................. 35 7.2.2. Test definition................................................................................................. 35 7.2.3. Replacement keys........................................................................................37 7.2.3. Replacement keys.......................................................................................... 37 7.2.4. Execution sequence.....................................................................................37 7.2.4. Execution sequence.......................................................................................37
8. In-database directory service.......................................39 8.1. Authentication................................................................................................... 39 8.2. Authorization..................................................................................................... 39 8.3. Typical setup..................................................................................................... 39 8.4. Changing the user password.............................................................................40
iKnowBase System Administration
5|Page
1.Summary This document is a catch-all for information about the technical workings of an iKnowBase installation. As this is not well covered in the current documentation set, this document is released outside the general product release cycle. Also, to ensure timely release, we have prioritized function above form. Note also that while the architectural information is generally applicable to any iKnowBase release in the 5.x-series, the tools description is based on iKnowBase 5.4.
iKnowBase System Administration
6|Page
2.Overall architecture 2.1. The iKnowBasemodules The iKnowBase installation delivered from e-vita comprises a number of various modules: •
•
•
The database repository, running in Oracle Database 10gR2 or newer. The database again comprise multiple modules: o
The metadata that defines the content and the application
o
The actual content that you store in iKnowBase
o
PL/SQL-modules (executable code) that is used by iKnowBase
o
PL/SQL-modules (executable code) that expose a number of PL/SQL-portlets to Oracle Portal. (Note that these are deprecated, in favor of similar java-based portlets)
The ikbViewer java web application, typically available as http://server.domain.com/ikbViewer. This again comprise a number of modules: o
A set of portlet providers that provide portlets to Oracle Portal (/ikbViewer/providers).
o
A page engine, for running iKnowBase pages directly, without Oracle Portal (/ikbViewer/page).
o
A PLSQL proxy engine (/ikbViewer/pls)
o
A system administration module, for monitoring the performance of iKnowBase (/ikbViewer/sysadmin)
o
A developer module, for assisting the developer during page engine development (/ikbViewer/developer.do)
The ikbadminportlets java web application, typically available as http://server.domain.com/ikbadminportlets. This comprise only a single set of modules: o
•
A portlet provider used to provide metadata and user administration functions
Various other components, only mentioned in passing: o
The ikbWebServices java web application, typically available as http://server.domain.com/ikbWebServices.
o
The EmailReader program, useful for loading email from a number of POP mailboxes into iKnowBase.
o
The iKnowBase connector for Oracle Secure Enterprise Search (SES), useful for making iKnowBase content searchable through SES.
o
Client programs for Microsoft Office and OpenOffice.
iKnowBase System Administration
7|Page
2.2. iKnowBaserunningwith OraclePortal When iKnowBase runs alongside Oracle Portal, the logical architecture is shown below. Note that the webcache and apache modules are often the same. •
•
•
Portal o
Ekstern webcache
o
Apache
o
Oracle Portal (//server/portal)
iKnowBase Web providers o
Webcache
o
Apache
o
iKnowBase providers (//server/ikbViewer/providers/*)
iKnowBase plsql providers o
Webcache
o
Apache
o
Oracle Portal (//server/portal/pls)
o
iKnowBase database
2.3. iKnowBaserunningwith the pageengine When iKnowBase runs with the internal page engine, the logical architecture is shown below: •
External webcache (optional)
•
Apache http-server
•
iKnowBase page engine (//server/ikbViewer/page)
(TODO: Figure)
iKnowBase System Administration
8|Page
3.Monitoringthe iKnowBasecomponents 3.1. Databaselogging The various database components will log application events at various places and times.
3.1.1. Error log The table ikb_error_tab contains a lot of useful information for tracing or troubleshooting. To enable logging, you need to modify the package specification of the package “ikb_global_prefs”, setting the variable log_level. Legal values are shown in the code, but as of this writing they are ALL, DEBUG, ERROR, and OFF. To view the log, use a sql-tool to select from ikb_error_tab. This is often a useful start: SQL> select * from ikb_error_tab 2 order by timestamp desc;
3.1.2. Performancelog When tuning an iKnowBase installation, the ContentViewer and ContentSearch components are most susceptible to be slow, due to the open-ended possibilities. Therefore, the iKnowBase application will log slow SQL-statements to the table sql_logger. To enable, modify the value “log time consuming queries >=” in the domain pane. All queries using more than the entered value (in seconds) will be reported. To view the log, use a sql-tool to select from sql_logger. This is often a useful start: SQL> select * from sql_logger 2 order by tid desc;
3.1.3. Componentexecutionlog Some components, in particular the ContentViewer, is capable of producing log output visible at runtime. Enable this through the development admin (/ikbViewer/developer.do), or the “iKnowBase ContentServices Development Administrator” (http://server.domain.com/desktop/adminportletdata/cache). For the page engine, you may need to enable page controls (the same page). For portal, you will see portlet information at the bottom of the portlets.
iKnowBase System Administration
9|Page
3.2. Javaapplicationlogging The iKnowBase java applications all use log4j for logging, and they use it generously. By enabling full logging on the application, you will get a lot of information, and it will slow the application down.
3.2.1. Configuringlogging Configuration of the system is done as specified in http://logging.apache.org/log4j/. From a pragmatic point of view, it works like this: By default, the file log4j.properties, located in WEB-INF/classes in the application deployment directory, is used. To start with a different configuration, specify a java property “log4j.configuration” as a startup parameter to the application server. On our development servers, we often specify “-Dlog4j.configuration=log4j-development.properties” in the opmn/conf/opmn.xml-file. A fragment is shown below:
3.2.2. Log levels Logging using log4j is based on the concept of loggers and logging levels, which the log4j framework use to decide which log files to write to. In iKnowBase, the logger is generally the full name of the java class which created the log event, so that a logger specification of “com.iknowbase” will capture all events. As for log levels, the iKnowBase code generally uses these definitions: •
FATAL is used for errors which mean that the system as such is incapable of continuing operations.
•
ERROR is used for situations where the current request cannot be serviced.
•
WARN is used for situations where input values, privileges etc typically prohibits servicing a request, but where this is not necessarily an error
•
INFO is used for messages that may be useful during normal operations.
•
DEBUG is used for messages that explain the step-by-step progress of operations.
iKnowBase System Administration
10 | P a g e
•
TRACE is used for providing default descriptions of progress, typically by listing data values etc.
3.2.3. Samplelog configuration This is a partial log4j configuration file, showing the various elements: # The default destination file-prefix. This may be overridden as a system # property, otherwise the value below will be used. com.iknowbase.log4j.path=${oracle.j2ee.home} com.iknowbase.log4j.prefix=ikbViewer # General logfile destination log4j.appender.LOGFILE=org.apache.log4j.FileAppender log4j.appender.LOGFILE.File=${com.iknowbase.log4j.path}/ikbViewer.log log4j.appender.LOGFILE.layout=org.apache.log4j.PatternLayout log4j.appender.LOGFILE.layout.ConversionPattern=%d{ISO8601} %-5p %c{2} - %m %n log4j.appender.LOGFILE.threshold=warn # Choose what you want in the standard logs log4j.rootLogger=info,LOGFILE
As shown above, all logging at INFO-level or above will be passed to log file destinations for evaluation. The LOGFILE destination will only log WARN or above. To log all events, change both of these values to TRACE, and restart.
3.2.4. Monitoringloggingat run time Logging may be configured and log output may be seen in the sysadmin console, on /ikbViewer/ikb$console/logging/config.do
3.3. Performancemonitoring From iKnowBase 5.4 onwards, the ikbViewer web application is instrumented with performance monitors that count and time various operations. The log of executions may be seen from the sysadmin console, using /ikbViewer/sysadmin. This page shows the name of the monitor, the number of executions and timing characteristics. Note that min and max values might easily be outliers (extreme values that occur only once or twice, for example during the initial execution), so it may be useful to reset statistics once in a while, to see more typical executions. In many cases, the monitor name contains a 16-character long code (a GUID). Most often this is the identity of an object defined in the database, so this may be useful in identifying which components are involved in the various operations. The performance monitors can be seen at /ikbViewer/ikb$console/monitor/monitor.do.
iKnowBase System Administration
11 | P a g e
3.4. Metadatacache When using either the page engine or web-based portlets in Oracle Portal, you will be using the ikbViewer web application. This application maintains a cache of a lot of the metadata required to render pages. For example, in iKnowBase 5.4, the application caches the following entities: •
Pages
•
Templates
•
Content viewer preferences
•
HTML item preferences
•
Generic preferences
•
Labels
•
Prompts
3.4.1. Cacheclearingand invaliation This information is generally considered static in a running installation, and only change while developing an application. Still, to combat stale caches, iKnowBase employs two different strategies. First, the caches can be manually cleaned: •
For Oracle Portal, the “iKnowBase ContentServices Development Administrator” portlet provides a brief cache status along with a button to clear the cache. The portlet is generally available in the iknowbase development desktop, at http://server.domain.com/desktop/adminportletdata/cache.
•
Outside of portal, the cache can be cleared through pages at /ikbViewer/developer.do and /ikbViewer/sysadmin/cache.do.
Second, iKnowBase regularly checks for changes in the cache data. The interval for such checks is defined using an environment setting for the web application (web.xml, orion-web.xml), under the key “iknowbase/RequestMetadataInvalidationManager/minimumInterval”. The default setting is 10 seconds.
3.4.2. Cachemonitoring The status of the cache can be seen in the administration console, at /ikbViewer/ikb$console/cache/cache.do.
iKnowBase System Administration
12 | P a g e
3.5. Webapplicationenvironmententries(web.xml/ JNDI) Configuration of the ikbViewer application is partially done through web application environment entries, specified in web.xml and accessed through JNDI. Editing these variables is normally easily done through the application server’s web console (“enterprise manager” for OC4J). However, there are known bugs in the console, and it is not easy to see if your configuration changes are visible to the application. First, a bug in OC4J is that it is often required to specify all values in the enterprise manager console. Specifying only some leads to all values being ignores. Use the administration console (/ikbViewer/ikb$console/snoop/jndi.do) to see the actual values available to the iKnowBase application.
3.6. Performancetroubleshootingthe OC4J-container In case of performance problems with the OC4J container, the Oracle Application Server Performance Guide (http://download.oracle.com/docs/cd/B25221_04/core.1013/b25213/toc.htm) is a good companion. Before dwelling into the following sections, understand the options available in that document. (These are also required for further analysis below).
3.6.1. Threadinformation The web application container will generally execute a large number of threads. The administration console (/ikbViewer/ikb$console/snoop/threads.do) will display thread information.
3.6.2. Garbagecollection If you suscpect that garbage collection is an issue: •
Turn on garbage collection logging, using options such as –verbose:gc, -XX: +PrintGCDetails,
•
Look at options such as –XX:+AggressiveHeap
•
Look at adjusting available memory using the–Xms and –Xmx options.
iKnowBase System Administration
13 | P a g e
3.6.3. Maxedout CPU Normally, the java container should not max out the CPU of the host machine. If it does, look for a couple of things: •
Generate a couple of JVM thread dumps (http://www.crazysquirrel.com/computing/java/basics/java-thread-dump.jspx)
•
See if there are any unexpected thread locations.
iKnowBase System Administration
14 | P a g e
4.Administrationconsole The iKnowBase “/ikbViewer” application contains a console useful for gathering monitoring and performance information. This section describes briefly the various information screens available in the console. The console can be reached through “/ikbViewer/ikb$console”. Note that you will need to be a member of the “IKB_SYSADMINS” role.
4.1. Mainmenu This is the main menu, where you can select other submenus:
4.2. Java This section contains various metrics from the java virtual machine and the java environment.
4.2.1. Request This section contains information about the current web request:
iKnowBase System Administration
15 | P a g e
4.2.2. JVM This section contains information about the java virtual machine:
4.2.3. Threads This section contains information about the threads running inside the java virtual machine: iKnowBase System Administration
16 | P a g e
4.2.4. JNDI This section contains information about the WEB.XML-variables available through jndi:
4.3. Database This section contains information about the database currently connected iKnowBase System Administration
17 | P a g e
4.4. Cache This section contains information about the objects cached inside the java cache:
iKnowBase System Administration
18 | P a g e
4.5. Logging This section contains information about the logging system, both on the application server and on the database side.
4.5.1. Config This section contains a list of available log4j-configurations (for application server logging), with the option to load any of them:
4.5.2. Loggers This section contains a list of loggers (log sources) used by the iKnowBase application, with the option to change the log level for any of them.
iKnowBase System Administration
19 | P a g e
4.5.3. Appenders This section contains a list of log appenders (log destinations) used by the iKnowBase application.
By clicking on any destination name (the rightmost colum), you can navigate through the log content. Use the links in the column heading to navigate (first, previous, next, last):
iKnowBase System Administration
20 | P a g e
4.5.4. Database This page displays the content of the database log, from the table IKB_ERROR_LOG. Use the links in the column heading to navigate (first, previous, next, last):
iKnowBase System Administration
21 | P a g e
4.6. Monitor This page provides information from the monitors (probes) embedded in the iKnowBase application.
4.6.1. All This page lists all monitors:
4.6.2. Page This page lists probes related to all the pages known to the page engine. The page lists monitors even for pages that have not executed yet, which therefore has no data:
iKnowBase System Administration
22 | P a g e
By clicking on a page name, you will see monitors for all components on the selected page. The listing will also traverse the layout page hierarchy, for all information pertaining to a specific page request:
iKnowBase System Administration
23 | P a g e
5.Developmenttools 5.1. Sessiontracing From iKnowBase 5.4 onwards, the page engine is capable of keeping track of logging on a per-component and per-session basis, rather than only in a single global file. To run session tracing, you must enable a log4j-appender with the class “com.iknowbase.trace.log4j.TraceAppender”. This is done by default when using “log4j-debug.properties” as the log configuration file (see the chapter on “java application logging”). To use session tracing, go to the development page (/ikbViewer/developer.do), and click “enable trace”. After running a couple of operations, return, and see that the last 20 requests are listed:
By clicking on a trace session, you will see the log produced by the server during the execution of that request. A single trace session may further be divided into sub-sessions, shown under separate headings on the display:
iKnowBase System Administration
24 | P a g e
iKnowBase System Administration
25 | P a g e
6.Contentcaching iKnowBase is a fully dynamic publishing solution, in that it does not create static webpages but rather runs dynamic queries for all content. This means that solutions built using iKnowBase are extremely flexible, but it also means that page rendering is more expensive in terms of performance. iKnowBase uses an internal metadata cache to ensure the highest possible performance of content generation, as described in another chapter. This chapter, however, deals with caching content that has already been generated, to minimize the number of generation requests.
6.1. Contentcachingwith OraclePortal Oracle portal is one of the page assembly technologies that can be used with iKnowBase. When using Oracle Portal, content caching is managed by that product.
6.1.1. Understandingcachingin OraclePortal This chapter is an unmodified version of http://download.oracle.com/docs/cd/B14099_13/portal.1014/b19305/cg_archit.htm#sthre f59, ”Understanding caching in Oracle Portal”) OracleAS Portal caches data in the following locations: •
Browser – Data that does not change between requests can be cached in the browser, for example, expiry-based pages.
•
OracleAS Web Cache – Many types of portal data are stored in this in-memory caching system. See Section 1.3.1, "Understanding OracleAS Web Cache".
•
Portal Cache – Many types of portal data are also stored in this persistent file system-based cache. See Section 1.3.2, "Understanding Portal Cache".
OracleAS Portal uses three methods to cache Web pages and content: •
Invalidation-based caching is used by OracleAS Web Cache. An item remains in the cache until it is explicitly invalidated. For example, a user may update some item, requiring the cache to be invalidated. As part of the update, the OracleAS Metadata Repository or a Provider sends an invalidation message to OracleAS Web Cache. The next time there is a request for the invalidated item, it is refreshed in the cache. You can set the expiry time for invalidation-based caching. See Section 5.8.3.3, "Setting the Expiry Time for Invalidation-based Caching" for more information.
•
Validation-based caching is used by the portal cache. Before an item in the portal cache is used, Portal Services contacts the OracleAS Metadata Repository or a Provider to determine if the cached item is still valid.
iKnowBase System Administration
26 | P a g e
•
Expiry-based caching is used by the portal cache, OracleAS Web Cache, and browsers. Expiry-based portlets are cached in the portal cache, whereas, expiry-based assembled pages are cached in OracleAS Web Cache. A retention period for the item specifies how long it is valid in the cache, before a refresh is required. Pages that use expiry-based caching may also be cached in the user's browser.
Caching can be done at the following levels: •
User - A separate copy of the data is cached for each user.
•
System – A single copy of the data is cached for all users.
6.1.2. Cachingwith the iKnowBasePortlets Some iKnowBase Portlets have the capability of enabling caching, normally specified in number of minutes. By default, iKnowBase portlet caching is handled using validation-based caching (see above). In that scenario, Oracle Portal will contact the iKnowBase portlet provider for every portlet render request. However, when Oracle Portal has content in the cache, it will send information about that content to the provider. If that content is still valid, the provider will return immediately, without actually generating new content. It is possible to modify the cache policy to use Invalidation-based caching. The performance benefits are usually very small, and troubleshooting gets much harder. We therefore do not recommend switching unless strictly required. With both of these mechanisms, all cached content can be cleared by clearing the Oracle WebCache(s).
6.1.3. iKnowBase,OraclePortal and WebCache The iKnowBase portlet provider registration is set up up with the flag “Require Portal user specific session information”, so that the iKnowBase back-end server has identity that can be used to store information between requests, when required. However, the Oracle Portal implementation of this flag means that the parameters “_sessionid” and “_logintime” are added to the portlet provider execution URL. This, in turn, means that WebCache will now cache content per session, rather than per user. While this is good for some purposes, it is not so good for others, and with the way Oracle Portal implements this feature it is hard to get the best of both worlds. Hence, there are really three different options: •
Run the entire site with no portlet level caching, relying solely on page level caching. For many sites, this is a good solution.
•
Run the entire site portlet caching per session. This is the default set up when you specify portlet caching in iKnowBase, and works well when the majority of portlet views on cached portlets are from users who already viewed the portlet once.
iKnowBase System Administration
27 | P a g e
•
Run the entire site with portlet caching per username. This will sometimes be the most performant solution, but it is hardest to get right.
6.1.4. Portlet cachingper user rather than per session To enable portlet caching per username (shared cache between different sessions for the same user), you need to configure webcache. Note that anonymous (not logged on) users are perceived as logged on users with the username “PUBLIC”. To enable this, you need to configure web cache so that the cache key does not contain session specific information. In particular, you need to remove the two parameters “_sessionid” and “_logintime” from the cache key. Take the following steps: •
It is a good idea to have a separate site in WebCache used only by the iKnowBase providers. Set up a new hostname (server-ikbproviders.domain.com), and register the site. Change portlet registrations, and make sure that everything works as before.
•
With advanced logging enabled, run a couple of executions, and make sure you see events for [trace 11414] (Initial cache key is composed) and [trace 11415] (Final cache key is composed) for the provider url, and verify that these cache keys contain references to _sessionid and _logintime.
•
On the “Edit named site” page of the Enterprise Manager Web Cache configuration, chose the “advanced” tab. Add the parameters “_sessionid” and “_logintime” to the value for site-specific URL parameters to ignore. They should really be the only parameters that are ignored.
•
Restart the web cache, run a couple of requests, and verify in the log files that the cache key does indeed change.
iKnowBase System Administration
28 | P a g e
Two important notes: •
This procedure is a very specialized customization for Oracle Portal and WebCache: We cannot guarantee that this will not cause problems for your installation. An important remedy to this is running the iKnowBase portlet providers on a separate site, to isolate the cache key changes to only those portlets.
•
This implementation now means that Oracle Portal will now cache content per logged on user (and not session), while iKnowBase will still use the session for storing parameters etc. You need to be very sure that your iKnowBase application can handle this scenario.
6.1.5. Disablecachingfor usersother than public In some scenarios, it may be desirable to cache only content for the public (not logged on) user. This would probably be most useful when caching per user rather than per session, with the added goal of avoiding filling the cache with content for logged on users. To do so, select either the PublicOnlyValidationCacheManagerFactory or PublicOnlyInvalidationCacheManagerFactory cache manager factory using the mechanism described under “Selecting cache method”.
iKnowBase System Administration
29 | P a g e
6.1.6. Selectingcachemethod It is possible to select the cache method used by iKnowBase portlets. To do so, you need to modify the web application environment setting XXX. Use enterprise manager, select the ikbViewer applicaton and then the iKnowBase-*-ikbViewer web module, and under the administration tab select Environment Entry Mappings. Change the entry iknowbase/jpdk/cacheManagerFactory into one of these values: •
com.iknowbase.jpdk.cache. ValidationCacheManagerFactory for Validation-based caching.
•
com.iknowbase.jpdk.cache.InvalidationCacheManagerFactory for Invalidation-based caching.
•
com.iknowbase.jpdk.cache.PublicOnlyValidationCacheManagerFactory for caching only public request, using Validation-based caching.
•
com.iknowbase.jpdk.cache.PublicOnlyInvalidationCacheManagerFactory for caching only public requests, using Invalidation-based caching.
iKnowBase will log, at INFO-level, which factory is being used.
6.1.7. Troubleshootingcaching There are a number of facilities available when troubleshooting caching. First, create a simple test page with only one portlet, and make sure that the problem can be reproduced there. Then, enable logging on multiple layers, and look for clues in the relevant log files.
6.1.7.1. Enablingwebcachelogging First, enable webcache logging. From enterprise manager, select WebCache, Logging, and set log levels as shown below:
iKnowBase System Administration
30 | P a g e
With the event log set to trace, the event log file will contain very detailed information on cache progression. Important event are for example [trace 11414] Initial cache key is composed, [trace 11415] Final cache key is composed, [trace 11338] URL is in the cache, [trace 11347] the cached object is garbage, [trace 11344] Returning a freshly cached object.
6.1.7.2. EnableiKnowBaselogging For information on the cache directives that iKnowBase produces, enable logging of the package com.iknowbase.jpdk.cache. The log4j configuration file “log4j-development.properties” has a template for logging to PORTLETCACHE. Enable this for detailed output on what portal cache mechanisms are used, and what requests are made for caching.
iKnowBase System Administration
31 | P a g e
6.2. Contentcachingwith the pageengine When using the page engine, there are two caches in play: •
The external webcache, in front of the web server
•
Page Engine internal caching
The external webcache is configured as specified in the webcache documentation; this is outside the scope of this document. http://download.oracle.com/docs/cd/B14099_19/caching.htm contains the documentation for the 10.1.2-release of Oracle WebCache. As of iKnowBase 5.3, the Page Engine provides no internal content cache mechanisms, although this is planned for future releases. Please note, though, that the reduced complexity of the infrastructure makes page production and assembly within the page engine much faster than the similar operations in a full-blown portal scenario.
iKnowBase System Administration
32 | P a g e
7.Performancetestingusingthe TestRunner iKnowBase comes with a load testing tool called the TestRunner, found as a single jar-file called “iKnowBase-version-TestRunner.jar”. The TestRunner is a standalone version of the page engine, and will execute and render pages exactly the same way that the iKnowBase application itself will. However, being a standalone program, it is not affected by limitations on the application server infrastructure, or caching set up using WebCache or the like.
7.1. Execution The testrunner is executed from the command line, as shown below, and will then respond with a usage message: C:\> java -jar target\dist\iKnowBase-WORK-Test.jar Usage: java -jar Read between the lines, and see a sample property file: ###################################################################### # # This file contains one suite named "default" default.url=jdbc:oracle:thin:username/password@//machine.example.com:1521/or cl.example.com default.tests=frontpage # # The test "frontpage" # prefix "frontpage." matches the reference from the suite above # .user defines username to run as # .page defines page to run # .warmup is number of warmup iterations, before measurement # .threads is number of threads to run # .batchsize is number of requests per batch (sum for all threads) # .seconds is number of seconds to run. Batches are repeated until this # .detailsFile is a CSV file with detailed output. Always appended. # .summaryFile is a CSV file with summary output. Always appended. # .jtlFile is a jmeter result XML file. Always overwritten. # .htmlFile is a dump of a (separate) page execution # .simonFile is a dump of the Simon monitors after the test itself # For filenames, use ${date} to substitue date as YYYYMMDD-HHMISS frontpage.name=Frontpage frontpage.user=orcladmin frontpage.page=/xnext/accesspage/frontpage frontpage.warmup=1 frontpage.threads=0 frontpage.batchsize=3 frontpage.seconds=0 frontpage.detailsFile=target/PageRunner-xnet-frontpage-details.csv frontpage.summaryFile=target/PageRunner-xnet-frontpage-summary.csv frontpage.jtlFile=target/PageRunner-xnet-frontpage-${date}.jtl frontpage.htmlFile=target/PageRunner-xnet-frontpage.html frontpage.simonFile=target/PageRunner-xnet-simon.txt ######################################################################
iKnowBase System Administration
33 | P a g e
The output between the hashed lines can be used as a starting point for configuring your own property file. See the chapter “Configuration” below for more information. If you run it with proper parameters, the session may look like this: C:\> java -jar target\dist\iKnowBase-WORK-Test.jar Loading context for: classpath:org/javasimon/spring/monitoring*.xml,test-application-context.xml, applicationContextModel.xml,applicationContextWeb.xml User.dir=C:\ Object count in application context:96 Starting timed run: threads=0; count=3; seconds=0 Starting iteration 1; remaining=0 Run: status=200; length=36173; elapsed=6422 Run: status=200; length=36173; elapsed=7177 Run: status=200; length=36173; elapsed=8270 Summary: 28.09.2009 15:00:31; null; 3; 0; 36173; 21873; 7289; 6422; 6422; 8270; 8270;
However, the interesting output will be in the files specified in the property file under the “details” and “summary” specs: C:\> type target\PageRunner-xnet-frontpage-details.csv Timestamp; Path; Elapsed; Status; Length; 28.09.2009 14:38:16.283; /xnext/accesspage/frontpage; 8221; 28.09.2009 14:38:24.350; /xnext/accesspage/frontpage; 8066; 28.09.2009 14:38:32.007; /xnext/accesspage/frontpage; 7656; 28.09.2009 15:00:17.481; /xnext/accesspage/frontpage; 8270; 28.09.2009 15:00:24.659; /xnext/accesspage/frontpage; 7177; 28.09.2009 15:00:31.081; /xnext/accesspage/frontpage; 6422;
200; 200; 200; 200; 200; 200;
36173; 36173; 36173; 36173; 36173; 36173;
C:\> type target\PageRunner-xnet-frontpage-summary.csv Timestamp; Name; Count; Threads; AvgLength; SuiteElapsed; AvgElapsed; MinElapsed; pct10Elapsed; pct90Elapsed; MaxElapsed; 28.09.2009 14:38:32; null; 3; 0; 36173; 23949; 7981; 7656; 7656; 8221; 8221; 28.09.2009 15:00:31; null; 3; 0; 36173; 21873; 7289; 6422; 6422; 8270; 8270;
Here, two different tests have been executed, and the results have been stored. The files are in CSV-format, and will open easily in a spreadsheet such as Microsoft Excel or OpenOffice Calc. The results will append to the bottom of the file, so that it is easy to store history information to see how performance developes over time.
7.2. Configuration All configuration is done in a single property file: # # This file contains one suite named "default" default.url=jdbc:oracle:thin:user/pwd@//example.com:1521/orcl.example.com default.tests=frontpage # # # # #
The test "frontpage" prefix "frontpage." matches the reference from the suite above .user defines username to run as .page defines page to run .warmup is number of warmup iterations, before measurement
iKnowBase System Administration
34 | P a g e
# .threads is number of threads to run # .batchsize is number of requests per batch # .seconds is number of seconds to run. Batches are repeated until this # .detailsFile is a CSV file with detailed output. Always appended. # .summaryFile is a CSV file with summary output. Always appended. # .jtlFile is a jmeter result XML file. Always overwritten. # .htmlFile is a dump of a (separate) page execution # .simonFile is a dump of the Simon monitors after the test itself # For filenames, use ${date} to substitue date as YYYYMMDD-HHMISS frontpage.name=Frontpage frontpage.user=orcladmin frontpage.page=/xnext/accesspage/frontpage frontpage.warmup=1 frontpage.threads=0 frontpage.batchsize=3 frontpage.seconds=0 frontpage.detailsFile=target/PageRunner-xnet-frontpage-details.csv frontpage.summaryFile=target/PageRunner-xnet-frontpage-summary.csv frontpage.jtlFile=target/PageRunner-xnet-frontpage-${date}.jtl frontpage.htmlFile=target/PageRunner-xnet-frontpage.html frontpage.simonFile=target/PageRunner-xnet-simon.txt
There are two distinct types of sections in the file, the test suite definition and the test definition
7.2.1. Test suite definition A configuration file can contain many test suite definitions, where each definition comprises two properties. In the example below, a single testsuite named “default” is defined, identified by the prefix to each property: default.url=jdbc:oracle:thin:user/pwd@//example.com:1521/orcl.example.com default.tests=frontpage,myprofile,someothersuite
Each testsuite has two properties: Name
Value
url
JDBC-specification of database to use, including username and password
tests
comma-separated list of tests to run
7.2.2. Test definition A configuration file can contain many test definitions. In the example below, a single test named “frontpage” is defined: frontpage.name=Frontpage frontpage.user=orcladmin frontpage.page=/xnext/accesspage/frontpage frontpage.warmup=1 frontpage.threads=0 frontpage.batchsize=3 frontpage.seconds=0 frontpage.details=target/PageRunner-xnet-frontpage-details.csv frontpage.summary=target/PageRunner-xnet-frontpage-summary.csv
iKnowBase System Administration
35 | P a g e
The test definition has several properties: Name
Value
name
Logical name of tests. Not used, except for display purposes
mkdir
The name of a directory to create before running the test. Can contain replacement keys, for example to generate a directory containing the date and time of a test run.
user
Name of user which will be used for running the test. Must match the username in the “IKB_USERS” table exactly. Has the same effect as logging in to the web application as this user.
path
Path to page(s) to run. This is in fact a regular expression, so you can write expressions such as “/xnext/accesspage.*” to get all pages with a given prefix, or “.*” to get all pages in the repository. You can of course also specify a single path.
warmup
Number of times the page should run before timing starts. Useful to make sure that initial metadata is loaded before testing.
threads
Number of threads to use. •
Use 0 to execute everything in the main thread
•
Any other number creates that number of threads, and distributes the executions per batch across those.
batchsize
Number of page executions to run in each batch
seconds
Number of seconds to run, or more precisely: After this much time has elapsed, no more batches are executed. The algorithm works as follows: Run a batch. If the total run time (for the test) has not yet reached the number of seconds to run, start a new batch and test again. This means that the actual run time will exceed this value, but not more than one batch.
detailsFile
Filename for details file. Each page execution will be logged on a separate line, with five values separated by semicolon: timestamp, path, elapsed time (milliseconds), return code and length. The testrunner will always append to the details file. If you want to start over, delete the file before starting the testrunner.
summaryFile
Filename for summary file. Each batch will be logged on a separate line, with the following values: Timestamp, Name, Count, Threads, Average length, Sum elapsed, Average elapsed, minimum elapsed, 10th percentile elapsed, 90th percentile elapsed and maximum elapsed. All times are in milliseconds (1000 milliseconds to a second). The testrunner will always append to the details file. If you want to
iKnowBase System Administration
36 | P a g e
start over, delete the file before starting the testrunner. jtlFile
Filename for a jmeter-style result file.
htmlFile
Filename for the html file. If this is specified, the TestRunner will run the page once extra, and save the output generated by the page. Useful to verify that the test actually works as expected.
simonFile
Filename for a simon dump. This corresponds to the “monitor” tab on /ikbViewer/ikb$console, although formatted differently. This gives a per-component statistic which can be useful in finding slow components on a page.
7.2.3. Replacementkeys The TestRunner supports the use of simple replacement keys inside the filenames. Name
Value
${test}
Replacement key for the name of the current test, from the property named “test”.
${datetime}
Replacement key for the current date, on the format “yyyyMMdd-HHmmss”.
${path}
Replacement key for the path of the page being run. The return value is normalized to contain only the letters a-z and the numbers 0-9; everything else is replaced with an underscore (_). This key is very useful with a page specification of “*”, because then this replacement key can be used to distinguish between different pages.
7.2.4. Executionsequence Upon starting, the TestRunner will first try to load the URL: •
If the property “.url” exists, use this (where is specified on the command line)
•
Otherwise, use the property “url”
Next, it will check whether to run a single test, or a suite of tests: •
If the property “.tests” exists, it contains a comma-separated list of tests to run. Run them, in that order.
•
Otherwise, the command line parameter is itself a test. Run that.
The TestRunner executes in the following sequence, once per specified test:
iKnowBase System Administration
37 | P a g e
•
If “.warmup” is specified, it first runs the warmup executions
•
If “.htmlFile” is specified, it runs a single execution to generate html output, and stores that
•
Then it starts running batches, as long as specified
iKnowBase System Administration
38 | P a g e
8.In-databasedirectoryservice For certain application servers, iKnowBase supplies an embedded directory service which can be used to authenticate users. When this has been configured (see the installation guide for information), authentication requests are checked against the IKB_USER database table, and user authorization requests are checked against the IKB_GROUP tables.
8.1. Authentication For user authentication, the following database fields are in use: •
ikb_user.username, which contains the username used during logon.
•
ikb_user.password_algorithm, which contains the encryption (hash) algorithm used to encode the password. Today, this is always ‘SHA1’ for users with a set password.
•
ikb_user.password_digest, which contains the encrypted password.
Today, iKnowBase supports only the SHA-1 hash algorithm. For more information, refer to http://en.wikipedia.org/wiki/SHA_hash_functions or other sources.
8.2. Authorization Authorization requests are always checked against the IKB_GROUP-table, where the authorization principal is the external_key of the table. For most deployments, the following principals are supported: •
IKB_USERS allows access to most protected parts of the ikbViewer application itself.
•
IKB_SYSADMINS allows access to system administration functions.
•
IKB_DEVELOPERS allows access to development functions, such as the iKnowBase Development Studio.
8.3. Typical setup For a typical setup, do the following: •
Create three groups as shown above (IKB_USERS, IKB_SYSADMINS and IKB_DEVELOPERS).
iKnowBase System Administration
39 | P a g e
•
Make a users member of these groups in order to access relevant portions of the iKnowBase applications.
8.4. Changingthe user password To change user passwords, use one of these options: •
Set user passwords through the Development Desktop, from the user editor.
•
Use the QuickStart “setIkbPassword” command. For example, to set the password for the iknowbase user: java- jar Quickstart.jar mydb.properties setIkbPassword iknowbase pwd
•
Use PL/SQL directly, using the following command: BEGIN ikb_authenticate.set_user ('username', 'password'); END; /
iKnowBase System Administration
40 | P a g e
