Usemon Install Guide
Prerequisites
- The collector needs a JRE version >= 5.x
- TCP connectivity to the MySQL database on port 3306 from the machine running the collector
- UDP Multicast connectivity from each server running the agent to the server running the collector on 224.82.199.166:16200
- Latest version: usemon-distro-1.0-bin.tar.gz
Files and their reason for existence
The
<version>
part of the filename will vary depending on the version of Usemon that you are deploying.
Static files
- usemon-agent-java-
<version>
-jar-with-dependencies.jar - The Usemon agent responsible for extracting information from the running applications - usemon-agent-preinstrument-java-
<version>
-jar-with-dependencies.jar - Used to create the code needed to boostrap the agent on Java <=1.4 - usemon-collector-java-
<version>
-jar-with-dependencies.jar - Used to receive multicasted data from the agent and deliver them to the Usemon database
Generated files
- usemon-bootstrap.jar - Generated by the preinstrument tool for Java <=1.4 deployments
Step by step
Variables used in the guide
- $JAVA5_HOME - Java >= 5.x JRE or JDK home directory, eg. /usr/lib/jdk5/jre
- $USEMON_HOME - Usemon home directory (where the files were unpacked), eg. /opt/usemon
- (Optionally) $WAS_HOME - WebSphere home directory, eg. /opt/WebSphere/AppServer
- (Optionally) $RESIN_HOME - Resin home directory, eg. /opt/resin-3.1.6
Create the database schema
- There are two scripts located in usemon-collector-java-
<version>
-jar-with-dependencies.jar, which you need to execute with your favourite mysql tool: - sql/s00-create-db.sql
- sql/s01-create-db.sql
Do the preinstrumentation (Only Java <=4.2)
- cd $USEMON_HOME
- Run the usemon-agent-preinstrument-java-
<version>
-jar-with-dependencies.jar using the app server JRE. - Verify that the usemon-boostrap.jar file was created and that the $USEMON_HOME/logs directory was created
If you are running your app server with Java security enabled
Example: Add WAS security permissions
Add the following in $WAS_HOME/properties/server.policy
grant codeBase "file:${was.install.root}/usemon/-" {
permission java.security.AllPermission;
};The snippet assume $USEMON_HOME to be $WAS_HOME/usemon
Add the agent definition to the app server java process
Example 1: WebSphere 5.1 (Java <=1.4)
- In the WAS admin console to the following steps for each server to be instrumented
- Navigate to Application Servers > SERVERNAME > Process Definition > Java Virtual Machine
- Add system properties for the following keys (example values after the dash)
- - usemon.system.id - eg. mySystem
- - usemon.cluster.id - eg. myCluster
- - usemon.server.id - eg. myServer
- Prepend "$USEMON_HOME/usemon-agent-java-
<version>
-jar-with-dependencies.jar: $USEMON_HOME/usemon-bootstrap.jar" in the Boot Classpath (or in Generic JVM arguments defined by -Xbootclasspath/p) - Save and sync the nodes and restart the server
- When the server starts verify that the file usemon.log is either written to $USEMON_HOMR/logs or $WAS_HOME/logs
Example 2: Resin 3.1.6 (Java 6)
Example startup script (collector.sh) for the collector
#!/bin/sh
export JAVA_HOME=/usr/java/jdk1.5.0_11/jre
export PIDFILE=/tmp/collector.pid
EXEC_DIR=`dirname $0`
if [ -r $PIDFILE ]
then
echo "Collector seems to be running"
echo "Please remove $PIDFILE to force restart"
exit 4
fi
# Saves the PID into the temporary directory
echo $$ >$PIDFILE
exec /usr/java/jdk1.5.0_11/jre/bin/java -Xmx512m -Djdbc.url=jdbc:mysql://<<<usemon.database.host>>>/usemon \
-Dorg.usemon.logback.configfile=$USEMON_HOME/logback.xml \
-Dusemon.cache.ehcache.configfile=classpath \
-jar $EXEC_DIR/usemon-collector.jarThere is also a sample provided together with the collector. Unpack collector.sh and have a look.
Modifying the internal cache of the collector
Specifying -Dusemon.cache.ehcache.configfile=classpath indicates that the configuration of the internal cache should be loaded from the classpath, this is a reasonable default.
If you wish to change this, extract the file ehcache.xml from usemon-collector.jar and modify it to your liking.
The status of the internal cache will be reported every 5 minutes unless you specify otherwise with the property usemon.cahce.report.interval, which may be added to the command line of the collector.sh script.
Hi, where the usemon-distro-1.0-bin.tar.gz file can be downloaded?
The distribution should now be available on the download page. Sorry about the delay :-)
Hi, you have given two examples: one using WAS and another using Resin. My question is, is it work with JBoss?
need a JBoss guide , too.
i user myclipse 6.0.1, when i start usemon agent, it tells:
Error occurred during initialization of VM agent library failed to init: instrument Failed to load Premain-Class manifest attribute from E:\\tools\\monitor\\usemon\\usemon-distro-1.0-SNAPSHOT\\usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar
my vm arguments are: -Dusemon.system.id=adressa -Dusemon.cluster.id=test -Dusemon.server.id=adrtest -javaagent:"E:\\tools\\monitor\\usemon\\usemon-distro-1.0-SNAPSHOT\\usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar"
thinks
Does this work with weblogic using jrockit? has anyone tried?
Can I use useMon to monitor a Java Web Start application, assuming the client is willing to install the useMon agent on his PC?
I downloaded your application and I am trying to install it for WAS 6.1 running on Java 1.5 JVM.
When I used the command as given below I got the following error;
JVMJ9VM015W Initialization error for library j9jvmti23(-3): JVMJ9VM009E J9VMDllMain failed Could not create the Java virtual machine. Failed to load Premain-Class manifest attribute from /UseMon????/distribution/usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar
Could you please answer the following questions:- ould you please tell me how to install UseMon???? on Web Sphere 6.1?
- ow to configure our server to avoid the Pre-Main class error on java 1.5 system?
- f java -javaagent expects a premain class attribute as part of manifest file. I dont see that jar or java class as part of your distribution jars. Should we have to download different jar or something?
Any help on this would be greatly appreciated. Thanks.
Looks nice but I have problems to make it run. Part of it is due to a lack of deep knowledge in java and the fact that I try to install it in a WebLogic? 10.3 server. The problems are:
Can someone help me or shine a light on it?
Regards,
Marco
Can i run "usemon" as an independent program? i.e. from command line (not involving any app servers?) The other questions are same as srkpriv (i.e. Q2 and Q3)
Is it possible to configure to have a network mask or can we have the option to specify the collector ip? TIA!
How do I know if it's working? I'm using JBoss, followed Example 1 steps and nothing is happening.
Can somebody write down the steps to use this on JBoss.
For Premain-class I specified com.usemon.agent.jdk5.JDK5Agent as Premain-class for instrumentation. This class was missing in the usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar. I downloaded the source and compiled it. I had to re-package the jar with modified Manifest.mf. Added the following entry to Manifest.mf
As someone who actually took the source and got it running from scratch i can maybe offer a few insights into the process:
Q: Will it be able to monitor my standalone application without J2EE server A: Most likely. You will have to configure which POJO -s to instrument (usemon-agent.properties is the file you want). Otherwise just use -javaagent command line parameter for JDK5+ or follow the preinstrument steps for JDK1.4 The command line parameter for preinstrument is "java -Xbootclasspath/p:/path/to/usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar:/path/to/usemon-bootstrap.jar"
The steps for getting agent running are pretty universal so it works for standalone, tomcat, jboss, weblogic, whatever. I have so far gotten it running for tomcat, weblogic and standalone without need to recompile anything.
Q: How do i change properties? They're packed inside jar -s. A: Extract properties file (or create one from scratch) and put it in your $CLASSPATH before usemon .jar files
Q: It complains about not finding Premain-class in manifest with JDK5+ A: The instructions are faulty. For JDK5+ you will have to use usemon-agent-jdk5-java-1.0-SNAPSHOT-jar-with-dependencies.jar instead of usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar
Q: How do i setup the collector? A: Collector is a standalone program which again packs its own properties inside JAR (usemon-default.properties). You will have to edit these (its basically mysql connection parameters) and edit the provided collector.sh to remove any jdbc references (or vice versa, override all properties in collector.sh)
Q: I have the agent and collector running but nothing seems to be happening A: This is a tough one. Usemon doesnt do very extensive logging and its configuration options are a bit lacking at the moment. I'll try to shed some light into it however:
1) Monitor usemon.log on agent side to see if agent is actually collecting samples and sending them. It should look something like: Thread-28DEBUG Transferred 4 usage objects to the publisher
2) If thats happening but collector log is quiet and empty, first try to exclude network problems. Good way in linux is to use command "tcpdump ip multicast" to monitor multicast traffic and see whether usemon multicast data reaches your collector. You should periodically get a bunch of lines from tcpdump like: IP someserver.int.33633 > 224.82.199.166.16200: UDP, length: 1067
3) Check if the computer you run collector from is not multihomed (ie. has more than one network adapter). I am not sure about the exact details but atleast once i've seen that Java binds multicast socket only to the interface that has default route. Unfortunately you cannot solve that with configuration, you'll have to modify the source (AbstractMulticastClient?.java) to bind to the specific interface
Q: How do i actually see the results? How do i run reports? A: There are a bunch of SQL scripts in SVN that should give you the basic idea. They're located in module usemon-service-java. As for GUI, this is a bit tricky one as i havent managed to do that myself yet. I got the GWT webapp running but so far it has failed to produce any meaningful report.
Can this be used with TOMCAT?
I setup the agent and collector. Wrote a simple Java console program to test it. This is what I see in the agent usemon.log. Why is it NOT publishing any objects ? It always say 0.
13.10.2008 08:30:13 main INFO Usemon agent initialized 13.10.2008 08:30:13 main INFO Usemon Publisher created! 13.10.2008 08:30:13 Usemon Publisher Thread (id:1223901013789) INFO Usemon publisher started 13.10.2008 08:30:13 Usemon Publisher Thread (id:1223901013789)DEBUG Sleep 15 seconds. Have sent 0 object so far, size of sender queue is now 0 ... ...
14.10.2008 10:06:53 Usemon Publisher Thread (id:1223992223329)DEBUG Sleep 15 seconds. Have sent 0 object so far, size of sender queue is now 0 14.10.2008 10:07:08 Usemon Publisher Thread (id:1223992223329)DEBUG Sleep 15 seconds. Have sent 0 object so far, size of sender queue is now 0 14.10.2008 10:07:23 Usemon Publisher Thread (id:1223992223329)DEBUG Sleep 15 seconds. Have sent 0 object so far, size of sender queue is now 0
Hi,
I was trying to use UseMon? with JBoss4.2.3GA.With the following settings:- set JAVA_OPTS=%JAVA_OPTS% -Xms128m -Xmx512m -javaagent:%USEMON_HOME%usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar
But at command prompt following error is displayed:- Error opening zip file or JAR manifest missing : D:\usemon-distro-.0-SNAPSHOTusemon-agent-java-1.0 -SNAPSHOT-jar-with-dependencies.jar Error occurred during initialization of VM agent library failed to init: instrument Press any key to continue . . .
I hope the settings are right??? any suggestion on this would be highly appreciated.
Thanks in advance
It would be great to finally get a binary release that would include correct jar also for jdk5+. I'm waiting to get test this but I haven't found time to checkout and build hole project as it would also require installing jdk 5 or older to compile it :(.
Hi,
i can't find any information how to set up usemon with tomcat. is that possible at all? how?
Cheers, Sven
While attempting to use UseMon? wiht JBoss4.2.2 I get an OutofMemory? Exception.
gent-jdk5-java-1.0-SNAPSHOT-jar-with-dependencies.jar -Dusemon.system.id="mySyst em" -Dusemon.cluster.id="myCluster" -Dusemon.server.id="myServer" -javaagent:C:\ programming\java\usemon-distro-1.0-SNAPSHOT\usemon-agent-jdk5-java-1.0-SNAPSHOT- jar-with-dependencies.jar -Dusemon.system.id="mySystem" -Dusemon.cluster.id="myC luster" -Dusemon.server.id="myServer" -javaagent:C:\programming\java\usemon-dist ro-1.0-SNAPSHOT\usemon-agent-jdk5-java-1.0-SNAPSHOT-jar-with-dependencies.jar -D usemon.system.id="mySystem" -Dusemon.cluster.id="myCluster" -Dusemon.server.id=" myServer" -Dprogram.name=run.bat -server -Xms128m -Xmx512m -Dsun.rmi.dgc.client. gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000
boss-4.2.2.GA\bin\run.jar
22:38:08,565 INFO TransactionManagerService? Binding TransactionManager? JNDI R eference
Exception in thread "CompilerThread1?" java.lang.OutOfMemoryError?: requested 3275 6 bytes for ChunkPool?::allocate. Out of swap space? Press any key to continue . . .
Any ideas?
Thanks
sorry about the last comment. I rebooted the machine and I was able to start JBOSS fine following same steps as w...@bill.ee.
How can I become a member to contribute to this project? I would like to create some startup scripts to facilitate the process of deploying usemon. For example to start the controller, and agent using JDK 1.5. Also I attempted to use the export of data in GraphML and GML but the data came out to look the same and not in the XML format. I am not sure if this feature is supposed to be working yet?
Thanks!
Hi,
I have been able to (seemingly) get the agent running on jboss (attached the javaagent as mentioned above) and i started the collector which says its running. My problem is im not seeing any data.
The log on the jboss side keeps telling me the following: 5.11.2008 16:07:54 Usemon Publisher Thread (id:1225897359676)DEBUG Sleep 15 seconds. Have sent 0 object so far, size of sender queue is now 0 and it has this to say about my servlet: 05.11.2008 16:07:54 http-192.168.84.33-8080-1 INFO com.amp.xterm.servlet.PixelParserServlet? is of type Servlet and will be instrumented
On the collector side all i get is this: 6:04:04.816 main? INFO org.usemon.collector.Collector - Usemon Collector started 16:09:04.778 usemonCacheStats? INFO o.u.s.DimensionCacheManagerImpl? - There are 0 active dimension caches
The database is set up according to the tutorial, but as the logs tell me, nothing is happening. Any help will be most appreciated as I am about to start a major re-factoring project of a legacy system.
-Mats
i cannot find where to put database user/password for the collector
a policy file with an AllPermission??...that would not be allowed even in our development environment.
have found db stuff set up jpetstore in tomcat with an agent, created the database, started a collector
I bought a parrot but all i get is
17.11.2008 22:15:25 http-8080-1 INFO com.mysql.jdbc.Statement is of type SQLStatement and will be instrumented ... 17.11.2008 22:15:54 Usemon Publisher Thread (id:1226956509283)
DEBUG Sleep 15 seconds. Have sent 0 object so far, size of sender queue is now 0 in the usemon.log
and in the collector
MulticastClient?? on 224.82.199.166:16200 started MulticastClient?? on 224.82.199.166:16201 started 22:14:34.994 main?
INFO org.usemon.collector.Collector - Usemon Collector started
Any one have ever tried to use usemon under windows? Or any one could post the steps of how to do this please? thanks!
Can this be used under tomcat server. Will this support Tomcat Load balanced using mod_JK
I tried using Usemon with Weblogic 9, JRockit BEA JRockit(R) (build R26.0.0) with agent jdk5 (as written above) after compiling it on JRockit VM but the result is VM hang after printing "Usemon log will be written to /usr/local/bea92/user_projects/domains/dev/logs/usemon.log". No information is written to any server and domains logs.
Usemon.log contains: 09.04.2009 09:23:55 Main Thread INFO Usemon agent initialized 09.04.2009 09:23:55 Main Thread INFO Usemon Publisher created!
Does anyone know how to deal with it? Have anyone run Usemon on WebLogic??
Can this be configured against any other databases then MySQL.
When i added <jvm> parameters to Resin 3.1.9 with JDK 1.6.0 on RH linux 4 . I am getting the following error . Failed to find Premain-Class manifest attribute in /opt/usemon/usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar . Error occured during initlisation of VM agent library failed to init : instrument . Can any one of you help on this .
I extracted the usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar file and added the following entry in the Manifest file .After that i am getting and error Error occured during initalisation of VM could not find agent library on the library path or in the local directory :resin
This is what iadded in the Manifest Manifest-Version: 1.0 Archiver-Version: Plexus Archiver Created-By: 1.5.0_16-133 (Apple Inc.) Premain-Class: com.usemon.agent.instrumentation.RootInstrumentor?
Any help on this could be appriatiated