[jopr-commits] JOPR SVN: r1173 - docs/enterprise/JON/2.3/Installation_Guide/en-US.
jopr-commits at lists.jboss.org
jopr-commits at lists.jboss.org
Wed Sep 9 01:11:50 EDT 2009
Author: smeehan
Date: 2009-09-09 01:11:50 -0400 (Wed, 09 Sep 2009)
New Revision: 1173
Added:
docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Best_Practices.xml
Modified:
docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml
Log:
Addition of Best Practices Guide
Modified: docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml
===================================================================
--- docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml 2009-09-09 04:58:57 UTC (rev 1172)
+++ docs/enterprise/JON/2.3/Installation_Guide/en-US/Installation_Guide.xml 2009-09-09 05:11:50 UTC (rev 1173)
@@ -14,7 +14,7 @@
<xi:include href="Command_Line_Interface_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Initial_Auto_discovery_and_Import.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="High_Availability_Configurations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-<!-- <xi:include href="JON_Best_Practices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <xi:include href="JON_Best_Practices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
Added: docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Best_Practices.xml
===================================================================
--- docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Best_Practices.xml (rev 0)
+++ docs/enterprise/JON/2.3/Installation_Guide/en-US/JON_Best_Practices.xml 2009-09-09 05:11:50 UTC (rev 1173)
@@ -0,0 +1,665 @@
+<?xml version='1.0'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter id="Installation_Guide-JON_Best_Practices">
+ <title>JON Best Practices</title>
+
+
+ <para>
+ The following sections will provide you with some best practices you can use when setting up and running your JBoss ON environment.
+ </para>
+
+
+ <section id="Installation_Guide-JON_Best_Practices-JBoss_App_Servers">
+ <title>Best Practices for Managing JBoss App Servers</title>
+
+ <section id="Installation_Guide-JBoss_App_Servers-DynaGroups">
+ <title>DynaGroups</title>
+
+
+ <para>
+ Utilize the DynaGroups feature by setting up GroupDefinitions that can automatically group resources with certain attributes. Set an update period to have the groups automatically recalculate themselves.
+ </para>
+
+ <formalpara>
+
+ <title>
+ JBoss AS Clusters
+ </title>
+
+ <para>
+ Use the template definition for "JBoss AS Clusters in the system" to automatically create a separate group for each set of jboss nodes in a cluster.
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>
+ Down Resources
+ </title>
+
+ <para>
+ Create a handy group of down resources with the "All Down Resources" template.
+ </para>
+ </formalpara>
+
+</section>
+
+
+ <section id="Installation_Guide-JBoss_App_Servers-Useful_Alerts">
+ <title>Useful Alerts</title>
+
+
+
+ <formalpara>
+
+ <title>
+ JBossAS Server : JVM Free Memory
+ </title>
+
+ <para>
+ Alert on this getting < 10MB to indicate the app server may be about to go out of memory.
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>
+ Data Source: Available Connections
+ </title>
+
+ <para>
+ Alert on this getting too low, to know when your app is about to run out of free database connections
+ </para>
+ </formalpara>
+
+
+ <formalpara>
+
+ <title>
+ Tomcat Connector: Error Count
+
+
+ </title>
+
+ <para>
+ Alert on this being > 0 to find out when your web apps are responding with errors to requests. See also 'Web Application (WAR) : Errors while processing' for information on individual web apps.
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>
+ Tomcat Connector: Maximum Request Time
+ </title>
+
+ <para>
+ Alert on this going above say 15sec, to indicate your web apps are running slow. See also 'Web Application (WAR) : Max. Servlet Resp. Time' for information on individual web apps.
+ </para>
+ </formalpara>
+
+
+ <formalpara>
+
+ <title>
+ Tomcat Connector: Request count per Minute
+
+
+ </title>
+
+ <para>
+ Monitor this to see how load on your app changes during the day/week. See also 'Web Application (WAR) : Requests served per Minute' for information on individual web apps.
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>
+ EJB3 Session Bean : Method Invocation Time
+ </title>
+
+ <para>
+ Collect the minimum, maximum, and average invocation times for each of the methods exposed by an EJB. Useful to monitor responsiveness of critical backend systems, e.g. EJBs calling into DBs or EISs.
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>
+ JMS Queue : Messages in Queue
+
+
+ </title>
+
+ <para>
+ Create an alert with a dampening rule on this metric to see if messages are backing up in the queu. Look at JMS Topic : All Message Counter' for the equivalent for topics.
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>
+ Hibernate : viewQueries operation
+ </title>
+
+ <para>
+ Schedule this operation and review its output regularly to determine the most used/expensive SQL in your hibernate app.
+ </para>
+ </formalpara>
+
+</section>
+
+ <section id="Installation_Guide-JBoss_App_Servers-JBoss_App_Server_Setup">
+ <title>JBoss App Server Setup</title>
+
+ <formalpara>
+
+ <title>
+ Management invoker security
+
+
+ </title>
+
+ <para>
+ always secure invoker endpoints
+ </para>
+ </formalpara>
+
+ <formalpara>
+
+ <title>
+ configuration
+ </title>
+
+ <para>
+ Symlinking is common for externalizing configs (mostly xml), makes upgrading easier
+ </para>
+ </formalpara>
+
+ <para>
+ Parametrized configurations by further externalizing environment variables how to leverage check config against init files
+ </para>
+
+
+
+ <formalpara>
+
+ <title>
+ application management
+
+
+ </title>
+
+ <para>
+ Use deploy dir or farm, sometimes symlinks to common deploy dir company wide
+ </para>
+
+ </formalpara>
+
+ <para>
+ Turn autodeploy off so that accidental touches to files do not cause redeploys
+ </para>
+ <para>
+ Application upgrade - side-by-side or rolling restart, scripted solution and coordinate with load balancer
+ </para>
+
+
+
+</section>
+ <section id="Installation_Guide-JBoss_App_Servers-Common_Issues">
+ <title>Common issues</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ running out of file handles
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ http threads, work thread, conn pools
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ incomplete deployments / undeployments
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ running out of sockets
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ lock contention / jvm deadlock detection
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ run out of jdbc connections
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ slow memory leaks
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ load (for physical machine) and latency
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ lockup detection
+ </para>
+ </listitem>
+ </itemizedlist>
+
+</section>
+ <section id="Installation_Guide-JBoss_App_Servers-Debugging_issues">
+ <title>Debugging issues</title>
+
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ determine final/last state just before failure: heap, seg fault, remote restart, system was rebooted, etc
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ have "test" application that you can hit in an isolated format to verify top-to-bottom health of connection from http entry to db and back
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ delta analysis - highlight metric spikes to signify unusual or unanticipated things
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ rate of change analysis - acceleration of metric value deltas over time load simulation against some app
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+</section>
+
+ <section id="Installation_Guide-JBoss_App_Servers-Log_tracking">
+ <title>Log tracking</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ look for error counts, number of times so-and-so occurred
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ transaction rollback messages
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ any network timeout issues, any lower-level issues such as syslog messages, kernel panic, daemons dying log / list of remote JMX commands sent to app server
+ </para>
+ </listitem>
+
+
+ </itemizedlist>
+
+</section>
+</section>
+
+
+ <section id="Installation_Guide-JON_Best_Practices-JBoss_Tomcat_Servers">
+ <title>Best Practices for Managing JBoss Tomcat Servers</title>
+
+ <para>
+ The Tomcat plugin manages Tomcat servers provided by Apache or JBoss EWS. The earliest Tomcat5 version tested with this plugin is 5.5.23. The earliest Tomcat6 version tested with this plugin is 6.0.18.
+ </para>
+
+
+ <section id="Installation_Guide-JBoss_Tomcat_Servers-Monitoring_Tomcat_Server">
+ <title>Enabling Jopr monitoring of your Tomcat Server</title>
+
+
+ <important>
+ <title>Important</title>
+ <para>
+ Java5 or higher is required when running Tomcat.
+ </para>
+ </important>
+
+ <para>
+ The JBoss ON Agent should automatically discover Tomcat Server processes and they can be imported into inventory. But the resources will have DOWN availability until they are properly JMX enabled.
+ </para>
+
+ <para>
+ Users of JBoss EWS have hooks already provided and should start by reading the RUNNING.txt in their Tomcat root directory. That includes instructions similar to those below but where possible the scripts and configuration files have already been seeded with comments and commented out settings and/or declarations.
+ </para>
+
+ <para>
+ Tomcat management is performed by utilizing the JMX interface provided by Tomcat. As such, remote JMX management needs to be enabled. To do this add the following section near the top of your bin/startup.sh (adapt for windows as necessary):
+ </para>
+
+<screen>
+# JON/Jopr Management
+#
+# To enable Tomcat for JON/Jopr management it is necessary to enable remote JMX access to the Tomcat server:
+# 1) Choose an unused and accessible portNum
+# 2) Update as necessary and uncomment the following lines:
+#
+# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.port=<port>"
+# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.ssl=false"
+#
+# 3) Follow the steps for secure access as described in the following url. Update as necessary
+# and uncomment the following lines based on authenticated (recommended) or unauthenticated access.
+# http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html.
+#
+# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.access.file=<access-file-path>"
+# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.password.file=<password-file-path>"
+# JAVA_OPTS="${JAVA_OPTS} -Dcom.sun.management.jmxremote.authenticate=false"
+# export JAVA_OPTS
+</screen>
+
+ <para>
+ Make the appropriate edits and (re)start the Tomcat server.
+ </para>
+
+ <para>
+ If you have configured JMX with authentication you will need to edit the Tomcat Server resource and add valid credentials. To do this navigate to the already imported Tomcat Server Resource. Continue to the Inventory->Connection subtab. Edit the definition, setting the user/password to valid settings. On successful update the Server availability should go green within a short period of time.
+ </para>
+
+</section>
+
+
+ <section id="Installation_Guide-JBoss_Tomcat_Servers-Response_Times_Tomcat_Server">
+ <title>Enabling Response Time metrics for your Tomcat Server</title>
+
+ <para>
+ Before enabling Response Time metric collection in your Tomcat Server Monitoring Schedules you need to add a servlet filter to your application's web.xml and add the filter jar, provided by Jopr.
+ </para>
+
+ <para>
+ It is typically case that the filter is deployed across all applications, in which case you can add the following to the global web.xml in the <tomcat>/conf directory.
+ </para>
+
+ <para>
+ Add the following filter and filter mappings. Uncomment when you want to activate the filter.
+ </para>
+
+
+ <section id="Installation_Guide-Response_Times_Tomcat_Server-Filter">
+ <title>Filter</title>
+
+
+ <para>
+
+<screen>
+<![CDATA[
+<!-- The RHQ Response Time Metric Filter. -->
+<!-- This filter gathers response time information for processed requests -->
+<!-- for all hosted applications. This requires that the -->
+<!-- rhq-rtfilter-X.X.X.jar also be placed properly in the Tomcat -->
+<!-- deployment. The jar file can be downloaded from the RHQ Server. -->
+<!-- Using the GUI, navigate to the Administration page. Then click -->
+<!-- 'Download Agent Connectors'. -->
+<!-- Download connector-rtfilter.zip. Unzip to extract the jar. -->
+<!-- -->
+<!-- Optional parameters -->
+<!-- -->
+<!-- chopQueryString Filter directly chops off the query parameters -->
+<!-- from the URL? Default is true. -->
+<!-- -->
+<!-- logDirectory Directory to which the logs are written. -->
+<!-- -->
+<!-- logFilePrefix Prefix to written logfile names. -->
+<!-- -->
+<!-- dontLogRegEx Patterns that should not be logged. -->
+<!-- -->
+<!-- matchOnUriOnly Apply the dontLog pattern to the URI only? -->
+<!-- -->
+<!-- timeBetweenFlushesInSec -->
+<!-- Seconds between auto flushes of the logfile. -->
+<!-- maxLogFileSize The maximum allowed size, in bytes, of the -->
+<!-- logfiles if a logfile exceeds this limit, the -->
+<!-- filter will truncate it; the default value is -->
+<!-- 5242880 (5 MB) -->
+<!-- vHostMappingFile Name of vhost mapping file. This properties file -->
+<!-- must be in the Tomcat process classpath. -->
+<!-- -->
+<!-- NOTE: When enabling, also uncomment the RhqRtFilter filter below. -->
+<!-- NOTE: When enabling, uncomment the start and end tags. -->
+
+<!-- start tag (also uncomment end tag)
+ <filter>
+ <filter-name>RhqRtFilter</filter-name>
+ <filter-class>org.rhq.helpers.rtfilter.filter.RtFilter</filter-class>
+-->
+
+<!-- Optional parameters. Note these typically remain commented. Also,
+ some of these values may be configurable on the relevant
+ RHQ Server resource, via the RHQ GUI.
+
+ <init-param>
+ <param-name>chopQueryString</param-name>
+ <param-value>true</param-value>
+ </init-param>
+ <init-param>
+ <param-name>logDirectory</param-name>
+ <param-value>/tmp</param-value>
+ </init-param>
+ <init-param>
+ <param-name>logFilePrefix</param-name>
+ <param-value>localhost_7080_</param-value>
+ </init-param>
+ <init-param>
+ <param-name>dontLogRegEx</param-name>
+ <param-value></param-value>
+ </init-param>
+ <init-param>
+ <param-name>matchOnUriOnly</param-name>
+ <param-value>true</param-value>
+ </init-param>
+ <init-param>
+ <param-name>timeBetweenFlushesInSec</param-name>
+ <param-value>73</param-value>
+ </init-param>
+ <init-param>
+ <param-name>flushAfterLines</param-name>
+ <param-value>13</param-value>
+ </init-param>
+ <init-param>
+ <param-name>maxLogFileSize</param-name>
+ <param-value>5242880</param-value>
+ </init-param>
+-->
+
+<!-- end tag (also uncomment start tag)
+ </filter>
+-->]]>
+
+</screen>
+
+
+</para>
+
+
+</section>
+
+
+ <section id="Installation_Guide-Response_Times_Tomcat_Server-Filter_Mapping">
+ <title>Filter Mapping</title>
+
+<screen>
+
+ <![CDATA[
+<!-- The mapping for the RHQ Filter -->
+<!-- To limit to only certain applications various filters can be -->
+<!-- defined. This will perform RT metric collection for all -->
+<!-- applications. -->
+<!-- -->
+<!-- Note: Uncomment only when also enabling the RhqRtFilter above. -->
+<!--
+ <filter-mapping>
+ <filter-name>RhqRtFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+ </filter-mapping>
+ -->
+]]>
+ </screen>
+
+
+
+</section>
+
+
+ <section id="Installation_Guide-Response_Times_Tomcat_Server-Jar_File_Placement">
+ <title>Jar File Placement</title>
+
+ <para>
+ The connector-rtfilter.zip file contains two jar files:
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ The rtfilter JAR
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The commons logging JAR
+ </para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ Placement of the jar files depend on the version of Tomcat.
+ </para>
+
+
+ <table id="tabl-Installation_Guide-Jar_File_Placement">
+ <title>Jar File Placement</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Tomcat Version</entry>
+ <entry>Instructions</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>5.5</para>
+ </entry>
+ <entry>
+ <para>Only one jar file is required:</para>
+ <para>Copy the rtfilter JAR file to <tomcat5>/common/lib> </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>6</para>
+ </entry>
+ <entry>
+ <para> 1. Copy the rtfilter JAR file to <tomcat6>/lib>
+ </para>
+ <para>2. Copy the commons logging JAR to <tomcat6>/lib></para>
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+
+ </section>
+
+</section>
+</section>
+<section id="Installation_Guide-JON_Best_Practices-Remote_Clients">
+ <title>Best Practices for Remote Clients</title>
+
+ <section id="Installation_Guide-Remote_Clients-Remote_Client_Approach">
+ <title>Deciding on a Remote Client Approach</title>
+
+ <para>
+ Jopr provides several options for remote clients:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ CLI (command line interface)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Java Client
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ WebService (WS) Client
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <section id="Installation_Guide-Remote_Client_Approach-CLI">
+ <title>Command Line Interface (CLI)</title>
+
+ <para>
+ The CLI is a powerful scripting tool for interacting with the Jopr Server. It offers Rhino Javascript as the scripting environment. Rhino is a Java-backed implementation of Javascript. Communication with the Jopr Server is through JBoss Remoting.
+ </para>
+
+ <para>
+ This is the recommended approach if you're looking for a remote script-based client.
+ </para>
+
+ </section>
+
+ <section id="Installation_Guide-Remote_Client_Approach-Java_Client">
+ <title>Java Client</title>
+
+
+ <para>
+ The power of the CLI is available in a programmatic way for remote clients written in Java. From the Java program one creates a Client object and works with it as if in the CLI:
+ </para>
+<screen>
+{
+ Client joprClient = new Client(...)
+ jopClient.getResourceManager().findResources(...)
+ ...
+}
+</screen>
+
+ <para>
+ This is the recommended approach for a programmatic remote client, if Java is an option. Communication with the Jopr Server is through JBoss Remoting.
+ </para>
+</section>
+
+ <section id="Installation_Guide-Remote_Client_Approach-Web_Services">
+ <title>Web Services</title>
+
+ <para>
+ For programmatic remote clients written in languages other than Java the Jopr Remote API methods are available as Web Services. Or, if for some reason a Java client does not want to utilize the Client object as mentioned above, a Web Service Java client is a possibility.
+ </para>
+ </section>
+
+
+ </section>
+
+</section>
+</chapter>
+
More information about the jopr-commits
mailing list