Author: prabhat.jha(a)jboss.com Date: 2008-08-21 16:44:23 -0400 (Thu, 21 Aug 2008) New Revision: 11727 Added: docs/enterprise/trunk/Tuning_Guide/.project docs/enterprise/trunk/Tuning_Guide/en/modules/clustering.xml docs/enterprise/trunk/Tuning_Guide/en/modules/hibernate.xml docs/enterprise/trunk/Tuning_Guide/en/modules/jbossweb.xml docs/enterprise/trunk/Tuning_Guide/en/modules/jvm.xml docs/enterprise/trunk/Tuning_Guide/en/modules/overview.xml Removed: docs/enterprise/trunk/Tuning_Guide/en/modules/sample.xml Modified: docs/enterprise/trunk/Tuning_Guide/en/master.xml Log: first draft of EPP tuning guide Added: docs/enterprise/trunk/Tuning_Guide/.project =================================================================== --- docs/enterprise/trunk/Tuning_Guide/.project (rev 0) +++ docs/enterprise/trunk/Tuning_Guide/.project 2008-08-21 20:44:23 UTC (rev 11727) @@ -0,0 +1,11 @@ +<?xml version="1.0" encoding="UTF-8"?> +<projectDescription> + <name>Tuning_Guide</name> + <comment></comment> + <projects> + </projects> + <buildSpec> + </buildSpec> + <natures> + </natures> +</projectDescription> Modified: docs/enterprise/trunk/Tuning_Guide/en/master.xml =================================================================== --- docs/enterprise/trunk/Tuning_Guide/en/master.xml 2008-08-21 13:20:40 UTC (rev 11726) +++ docs/enterprise/trunk/Tuning_Guide/en/master.xml 2008-08-21 20:44:23 UTC (rev 11727) @@ -3,18 +3,21 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <book lang="en"> <bookinfo> - <title>Change Title in master.xml</title> - <subtitle>Change SubTitle in master.xml</subtitle> - <releaseinfo>Change Release Info in master.xml</releaseinfo> - <releaseinfo>Change Release Info Date in master.xml</releaseinfo> + <title>JBoss Enterprise Portal Platform (EPP)</title> + <subtitle>Performance and Scalability Tuning Guide</subtitle> + <releaseinfo> 2.7 releases</releaseinfo> + <date> August 2008</date> <author> - <firstname>Your first name</firstname> - <surname>Your last name</surname> - <email&gt;your.email(a)your.domain.com&lt;/email&gt; + <firstname>Prabhat</firstname> + <surname>Jha</surname> + <email&gt;pjha(a)redhat.com&lt;/email&gt; </author> </bookinfo> <toc/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/sample.xml" /> - + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/overview.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/jbossweb.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/hibernate.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/clustering.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/jvm.xml" /> </book> Added: docs/enterprise/trunk/Tuning_Guide/en/modules/clustering.xml =================================================================== --- docs/enterprise/trunk/Tuning_Guide/en/modules/clustering.xml (rev 0) +++ docs/enterprise/trunk/Tuning_Guide/en/modules/clustering.xml 2008-08-21 20:44:23 UTC (rev 11727) @@ -0,0 +1,95 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="clustering"> + + <title>Clustering Tuning</title> + + <sect1> + <title> + Enable Buddy Replication for Portal and Portlet Session + Clustering + </title> + Portal and Portlet Session are merely wrappers around + HttpSession so most of HTTP session clustering optimization + applies to JBPP as well. EPP uses clustering configuration of + JBoss Web so changes go to + <filename> + jboss-web-cluster.sar/META-INF/jboss-service.xml + </filename> + . To enable buddy replication, change the value of + <emphasis>buddyReplicationEnabled</emphasis> + to true. + + </sect1> + + <sect1> + <title>Hibernate and JBoss Cache Configuration</title> + + EPP uses JBoss Cache as a second level cache for Hibernate and + this configuration is not defined in JBoss Cache definition used + for Portal and Portlet Session. Instead the configuration is + defined at + <filename> + jboss-portal-ha.sar/META-INF/jboss-service.xml + </filename> + + <sect2> + <title>Optimistic Locking (OL)</title> + Our tests have shown that optimistic locking performs better + under heavy load and it scales (horizontally) better as + well. However, your use case may not show the same behavior + and for you pessimistic locking may be a better + configuration. To enable optimistic locking, modify + TreeCache mbean definition as follows: + <programlisting role="XML"> + <![CDATA[ + <attribute name="NodeLockingScheme">OPTIMISTIC</attribute> + <attribute name="CacheMode">INVALIDATION_SYNC</attribute> + ]]> + </programlisting> + + <note> + If you have not disabled query cache, then you should + not use INVALIATION_SYNC as CACHE_MODE. Use REPL_SYNC + instead. + </note> + + </sect2> + <sect2> + <title>Pessimistic Locking (PL)</title> + When using Pessimistic Locking (PL), change isolation level + to READ_COMMITTED (RC). Please see <ulink url="http://lists.jboss.org/pipermail/jbosscache-dev/2008-July/00240... + to see why it is okay to relax the isolation level from + REPEATABLE_READ (RR). As expected, RC has better performance than RR. + </sect2> + + <sect2> + <title>Cache Eviction Policy</title> + If you disabled lazy loading, then you can control number of + objects and time they can reside in memory by configuring + EvictionPolicyConfig attribute of TreeCache at + <filename> + jboss-portal- ha.sar/META-INF/jboss-service.xml + </filename> + + <programlisting role="XML"> + <![CDATA[ + <attribute name="EvictionPolicyConfig"> + <config> + <attribute name="wakeUpIntervalSeconds">5</attribute> + <region name="/_default_"> + <attribute name="maxNodes">5000</attribute> + <attribute name="timeToLiveSeconds">1000</attribute> + </region> + </config> + </attribute> + ]]> + </programlisting> + </sect2> + + </sect1> +</chapter> + + + + + Added: docs/enterprise/trunk/Tuning_Guide/en/modules/hibernate.xml =================================================================== --- docs/enterprise/trunk/Tuning_Guide/en/modules/hibernate.xml (rev 0) +++ docs/enterprise/trunk/Tuning_Guide/en/modules/hibernate.xml 2008-08-21 20:44:23 UTC (rev 11727) @@ -0,0 +1,97 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="hibernate"> + + <title>Hibernate Tuning</title> + + <sect1> + <title>Enable/Disable Lazy Loading</title> + EPP assumes that number of portal pages and portlets window will + be large and hence does not cache these objects. As a result, + there could be many direct DB connection. But depending on use + case, lazy loading should be turned on and off partially or in + its entirety. Modify + <filename> + deploy/jboss-portal[-ha].sar/conf/hibernate/*/domain.hbm.xml + </filename> + and change + <emphasis>lazy=”extra”</emphasis> + to + <emphasis>lazy=”true”</emphasis> + or + <emphasis>lazy=”false”</emphasis> + <orderedlist numeration="upperroman"> + <listitem> + Modify attribute for the class + org.jboss.portal.core.impl.model.portal.ObjectNode + <programlisting role="XML"> + <![CDATA[ + <map name="children" inverse="true" cascade="none" fetch="select" lazy="true"> + <cache usage="transactional" /> //[“read-write” in non clustered] + <key column="PARENT_KEY" /> + <map-key type="org.jboss.portal.jems.hibernate.MagicString" column="NAME" /> + <one-to-many class="org.jboss.portal.core.impl.model.portal.ObjectNode" /> + </map> + ]]> + </programlisting> + </listitem> + <listitem> + Enable caching for displayNames for the class + org.jboss.portal.core.impl.model.portal.PortalObjectImpl + <programlisting role="XML"> + <![CDATA[ + <map name="displayNames" cascade="none" fetch="select" lazy="true" + table="JBP_PORTAL_OBJECT_DNAMES"> + <cache usage="transactional" /> <!-- [“read-write” in non clustered]--> + <key column="INSTANCE_PK" /> + <map-key type="locale" column="LOCALE" /> + <element type="string" column="TEXT" /> + </map> + ]]> + </programlisting> + </listitem> + <listitem> + Same as above for + <filename>hibernate/instance/domain.hbm.xml</filename> + for displayNames map. + </listitem> + <listitem> + Enable/disable lazy loading for set “users” in + <filename>hibernate/user/domain.hbm.xml</filename> + </listitem> + <listitem> + Disabling lazy loading implies there will be many + objects in memory. You can control how many objects + would need to reside in memory at a time and for how + long before they are evicted by modifying values at + <filename>conf/hibernate/*/ehcache.xml</filename> + in non clustered configuration. These parameters would + need to be changed as per the use case. For clustered + configuration, see the chapter on <xref linkend="clustering"> clustering + configuration.</xref> + </listitem> + </orderedlist> + </sect1> + + <sect1> + <title>Enable/Disable Query Cache</title> + EPP no longer uses query cache. Unless EPP is customized to use + query cache, it should be disabled by turning the value of + property "cache.use_query_cache" to false in following files: + + <itemizedlist> + <listitem><filename>hibernate/instance/hibernate.cfg.xml </filename></listitem> + <listitem><filename>hibernate/portal/hibernate.cfg.xml </filename></listitem> + <listitem><filename>hibernate/portlet/hibernate.cfg.xml</filename></listitem> + <listitem><filename>hibernate/user/hibernate.cfg.xml</filename></listitem> + </itemizedlist> + + Disabling query cache also allows to use<emphasis>INVALIDATION_SYNC</emphasis> as + CACHE_MODE when using optimistic locking with JBoss Cache and + Hibernate as explained in the clustering section. + </sect1> +</chapter> + + + + + Added: docs/enterprise/trunk/Tuning_Guide/en/modules/jbossweb.xml =================================================================== --- docs/enterprise/trunk/Tuning_Guide/en/modules/jbossweb.xml (rev 0) +++ docs/enterprise/trunk/Tuning_Guide/en/modules/jbossweb.xml 2008-08-21 20:44:23 UTC (rev 11727) @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="jbossweb"> + + <title>JBoss Web Tuning</title> + + <sect1> + <title> HTTP/AJP connector threads </title> + Increase number of HTTP/AJP connector threads. It's recommended + to set this value to <emphasis> 250 * n </emphasis> where n is number of CPU in your + server. Depending on nature of your application, this can be set + higher or lower. Modify value of maxThreads in in + <filename>deploy/jboss-web.deployer/server.xml</filename> + + <programlisting role="XML"> + <![CDATA[ + <Connector port="8009" address="${jboss.bind.address}" + protocol="AJP/1.3" emptySessionPath="true" enableLookups="false" + redirectPort="8443" maxThreads="1500" /> + ]]> + + </programlisting> + </sect1> + + <sect1> + <title> Global Session Timeout </title> + Reduce global session timeout to your need. The default value of + 30 min is too high for most use cases. A lower session timeout + results into a more consistent memory footprint and more + consistent throughput. Modify + <filename>deploy/jboss-web.deployer/conf/web.xml</filename> + <programlisting role="XML"> + <![CDATA[ + <session-config> + <session-timeout>15</session-timeout> + </session-config> + ]]> + </programlisting> + </sect1> +</chapter> Added: docs/enterprise/trunk/Tuning_Guide/en/modules/jvm.xml =================================================================== --- docs/enterprise/trunk/Tuning_Guide/en/modules/jvm.xml (rev 0) +++ docs/enterprise/trunk/Tuning_Guide/en/modules/jvm.xml 2008-08-21 20:44:23 UTC (rev 11727) @@ -0,0 +1,25 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="jvm"> + + <title>JVM Tuning</title> + + <sect1> + <title>Use Large Pages</title> + When using 64 bit Linux systems , use Linux's large memory page + support. Without large page support, increasing heap size may + not increase your performance. Modify JAVA_OPTS under + <filename>$JBOSS_HOME/bin/run.conf</filename> + to add -XX:+ UseLargePages. Please see EAP tuning guide or the + description at + <ulink + url="http://jbossworld.com/downloads/pdf/thursday/JBOSS_10-1050am_JB... + </ulink> + for the details. + </sect1> + + <sect1> + <title>Garbage Collection (GC) Tuning</title> + Depending on nature of your application, adding <emphasis> XX:+UseConcMarkSweepGC -XX:+UseParNewGC </emphasis> + may optimize GC collection behavior. + </sect1> +</chapter> Added: docs/enterprise/trunk/Tuning_Guide/en/modules/overview.xml =================================================================== --- docs/enterprise/trunk/Tuning_Guide/en/modules/overview.xml (rev 0) +++ docs/enterprise/trunk/Tuning_Guide/en/modules/overview.xml 2008-08-21 20:44:23 UTC (rev 11727) @@ -0,0 +1,19 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="overview"> + <title>Overview</title> + <para> + Since JBoss Enterprise Portal Platform (EPP) uses many services + of JBoss Enterprise Application Platform (EAP), all tunings and + configurations that are recommended for EAP apply to EPP as well + hence most of those tunings will not be covered here. Following + is a guideline that may help achieve best out of EPP. + </para> + + <para> + This document is intended for Portlet Developers, Portal + administrators, and those wishing to implement/extend the JBoss + Portal framework. + </para> + + +</chapter> Deleted: docs/enterprise/trunk/Tuning_Guide/en/modules/sample.xml =================================================================== --- docs/enterprise/trunk/Tuning_Guide/en/modules/sample.xml 2008-08-21 13:20:40 UTC (rev 11726) +++ docs/enterprise/trunk/Tuning_Guide/en/modules/sample.xml 2008-08-21 20:44:23 UTC (rev 11727) @@ -1,262 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="sample"> - <chapterinfo> - <author> - <firstname>Your first name</firstname> - <surname>Your last name</surname> - <email&gt;your.email(a)your.domain.com&lt;/email&gt; - </author> - </chapterinfo> - <title>Sample chapter</title> - <para>This is the beginning of the sample chapter.</para> - <sect1> - <title>sample section</title> - <para>This is the beginning of the sample section. It contains examples of how docbook should be used in the context - of a documentation for a Java related product.</para> - - <sect2> - <title>Bullet points</title> - <programlisting><![CDATA[ -<itemizedlist> - <listitem>Item1</listitem> - <listitem>Item2</listitem> - <listitem>Item3</listitem> -</itemizedlist> -]]></programlisting> - <para> - <itemizedlist> - <listitem>Item1</listitem> - <listitem>Item2</listitem> - <listitem>Item3</listitem> - </itemizedlist> - </para> - </sect2> - - <sect2> - <title>Interface or annotation reference</title> - <programlisting><![CDATA[ -<interfacename>mypackage.MyInterface</interfacename> -<interfacename>@MyAnnotation</interfacename> -]]></programlisting> - <para> - <interfacename>mypackage.MyInterface</interfacename> - <interfacename>@MyAnnotation</interfacename> - </para> - </sect2> - - <sect2> - <title>Class reference</title> - <programlisting><![CDATA[ -<classname>mypackage.MyClass</classname> -]]></programlisting> - <para> - <classname>mypackage.MyClass</classname> - </para> - </sect2> - - <sect2> - <title>Parameter reference</title> - <programlisting><![CDATA[ -<parameter>MyParameter</parameter> -]]></programlisting> - <para> - <parameter>MyParameter</parameter> - </para> - </sect2> - - <sect2> - <title>Method referece</title> - <programlisting><![CDATA[ -<methodname>myMethod()</methodname> -]]></programlisting> - <para> - <methodname>myMethod()</methodname> - </para> - </sect2> - - <sect2> - <title>Exception reference</title> - <programlisting><![CDATA[ -<exceptionname>mypackage.MyException</exceptionname> -]]></programlisting> - <para> - <exceptionname>mypackage.MyException</exceptionname> - </para> - </sect2> - - <sect2> - <title>A variable name</title> - <programlisting><![CDATA[ -<varname>myVariable</varname> -]]></programlisting> - <para> - <varname>myVariable</varname> - </para> - </sect2> - - <sect2> - <title>File reference</title> - <programlisting><![CDATA[ -<filename>MyFile</filename> -]]></programlisting> - <para> - <filename>MyFile</filename> - </para> - </sect2> - - <sect2> - <title>Literal reference</title> - <programlisting><![CDATA[ -<literal>null</literal> -<literal>1</literal> -<literal>"foo"</literal> -]]></programlisting> - <para> - <literal>null</literal> - <literal>1</literal> - <literal>"foo"</literal> - </para> - </sect2> - - <sect2> - <title>A constant</title> - <programlisting><![CDATA[ -<constant>MAX_VALUE</constant> -]]></programlisting> - <para> - <constant>MAX_VALUE</constant> - </para> - </sect2> - - <sect2> - <title>Inline code</title> - <programlisting><![CDATA[ -<code>System.out.println()</code> -]]></programlisting> - <para> - <code>System.out.println()</code> - </para> - </sect2> - - <sect2> - <title>Code or XML with a caption</title> - <programlisting> -&lt;example&gt; - &lt;programlisting&gt;&lt;![CDATA[public class MyClass -{ -} -]]&gt;&lt;/programlisting&gt; - &lt;caption&gt;This is the MyClass class&lt;/caption&gt; -&lt;/example&gt; -</programlisting> - <para> - <example> - <programlisting><![CDATA[public class MyClass -{ -} -]]></programlisting> - <caption>This is the MyClass class</caption> - </example> - </para> - </sect2> - - <sect2> - <title>A database name</title> - <programlisting><![CDATA[ -<database>MyDatabase</database> -]]></programlisting> - <para> - <database>MyDatabase</database> - </para> - </sect2> - - <sect2> - <title>A shell command</title> - <programlisting><![CDATA[ -<command>ls -l</command> -]]></programlisting> - <para> - <command>ls -l</command> - </para> - </sect2> - - <sect2> - <title>A shell example</title> - <programlisting><![CDATA[ -<screen>&lt;![CDATA[julien-viets-computer:~/java/jboss-portal-template/user-guide julien$ ls -l -total 8 -drwxr-xr-x 3 julien julien 102 Oct 19 18:14 build --rwxr-xr-x 1 julien julien 923 Oct 19 17:40 build.xml -drwxr-xr-x 6 julien julien 204 Oct 19 17:42 en -]]&gt;</screen> -]]></programlisting> - <para> - <screen><![CDATA[julien-viets-computer:~/java/jboss-portal-template/user-guide julien$ ls -l -total 8 -drwxr-xr-x 3 julien julien 102 Oct 19 18:14 build --rwxr-xr-x 1 julien julien 923 Oct 19 17:40 build.xml -drwxr-xr-x 6 julien julien 204 Oct 19 17:42 en -]]></screen> - </para> - </sect2> - - <sect2> - <title>Coloration</title> - <programlisting><![CDATA[ -<programlisting role="JAVA">&lt;![CDATA[ -package org.jboss.portal.foo; -public class Bar -{ -}]]&gt;</programlisting>]]></programlisting> - <programlisting role="JAVA"><![CDATA[ -package org.jboss.portal.foo; -public class Bar -{ -}]]></programlisting> - </sect2> - <sect2> - <title>Annotations</title> - <programlisting><![CDATA[ -<programlistingco> - <areaspec> - <area id="sample.annotation.line2" coords='2' /> - <area id="sample.annotation.line4" coords='4' /> - </areaspec> - <programlisting>&lt;![CDATA[Line 1: Foo -Line 2: Bar -Line 3: Toto -Line 4: FooBar -Line 5: Titi]]&gt;</programlisting> - <calloutlist> - <callout arearefs="sample.annotation.line2"> - <para>This is line 2</para> - </callout> - <callout arearefs="sample.annotation.line4"> - <para>This is line 4</para> - </callout> - </calloutlist> -</programlistingco> -]]></programlisting> - <programlistingco> - <areaspec> - <area id="sample.annotation.line2" coords='2' /> - <area id="sample.annotation.line4" coords='4' /> - </areaspec> - <programlisting><![CDATA[Line 1: Foo -Line 2: Bar -Line 3: Toto -Line 4: FooBar -Line 5: Titi]]></programlisting> - <calloutlist> - <callout arearefs="sample.annotation.line2"> - <para>This is line 2</para> - </callout> - <callout arearefs="sample.annotation.line4"> - <para>This is line 4</para> - </callout> - </calloutlist> - </programlistingco> - </sect2> - </sect1> - -</chapter>