My favorites | Sign in
Project Hosting will be READ-ONLY Thursday at 3:00pm UTC for up to 3 hours for network maintenance.
Project Home Downloads Wiki Issues Source
Search
for
InstallGuide  
How to install Usemon
Updated Feb 4, 2010 by steinar.cook

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:
    1. sql/s00-create-db.sql
    2. 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)

  • In the $RESIN_HOME/conf/resin.conf file add
  • - "
    <jvm-arg>
    -javaagent:$USEMON_HOME/usemon-agentjava-
    <version>
    -jar-with-dependencies.jar

    Unknown end tag for </jvm-arg>

    " to the JVM arguments section
  • - '<system-property usemon.system.id="adressa usemon.cluster.id="test" usemon.server.id="adrtest"/>' to the System property section
  • - Verify that the usemon.log file is written to $USEMON_HOME/logs when the server starts

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.jar

There 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.

Comment by luciano....@gmail.com, Oct 6, 2008

Hi, where the usemon-distro-1.0-bin.tar.gz file can be downloaded?

Comment by project member steinar.cook, Oct 6, 2008

The distribution should now be available on the download page. Sorry about the delay :-)

Comment by fernando...@gmail.com, Oct 6, 2008

Hi, you have given two examples: one using WAS and another using Resin. My question is, is it work with JBoss?

Comment by BM888...@gmail.com, Oct 6, 2008

need a JBoss guide , too.

Comment by norberth...@gmail.com, Oct 6, 2008

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

Comment by jonamtho...@gmail.com, Oct 7, 2008

Does this work with weblogic using jrockit? has anyone tried?

Comment by sjian...@gmail.com, Oct 7, 2008

Can I use useMon to monitor a Java Web Start application, assuming the client is willing to install the useMon agent on his PC?

Comment by srkp...@gmail.com, Oct 7, 2008

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:

  1. ould you please tell me how to install UseMon???? on Web Sphere 6.1?
  2. ow to configure our server to avoid the Pre-Main class error on java 1.5 system?
  3. 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.

Comment by marcodeb...@gmail.com, Oct 8, 2008

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:

  • When I add the -javaagent I get the error Failed to find Premain-Class manifest attribute in D:\\Programs\\UseMon\\usemon-agent-java-1.0-SNAPSHOT-jar-with-dependencies.jar (like srkpriv). When I google on this error it points me to a missing parameter in the package.
  • When I look in the JAR files I find quite a lot of files and classes that are twice in the jar file at the same location. Can this cause problems.
  • How do I define that the config files are at the file system (usemon-default.properties and usemon-agent.properties). I need to change some parameters in these files.

Can someone help me or shine a light on it?

Regards,

Marco

Comment by sajit.va...@gmail.com, Oct 8, 2008

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)

Comment by noxl...@gmail.com, Oct 9, 2008

Is it possible to configure to have a network mask or can we have the option to specify the collector ip? TIA!

Comment by mathcu...@gmail.com, Oct 9, 2008

How do I know if it's working? I'm using JBoss, followed Example 1 steps and nothing is happening.

Comment by saurabhj...@gmail.com, Oct 10, 2008

Can somebody write down the steps to use this on JBoss.

Comment by Archit.P...@gmail.com, Oct 11, 2008

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

Premain-Class: com.usemon.agent.jdk5.JDK5Agent

Comment by anastass...@gmail.com, Oct 13, 2008

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.

Comment by woleadet...@gmail.com, Oct 13, 2008

Can this be used with TOMCAT?

Comment by sriram.c...@gmail.com, Oct 14, 2008

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

Comment by shmvis...@gmail.com, Oct 15, 2008

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

Comment by ala...@gmail.com, Oct 15, 2008

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 :(.

Comment by skank...@gmail.com, Oct 20, 2008

Hi,

i can't find any information how to set up usemon with tomcat. is that possible at all? how?

Cheers, Sven

Comment by drgbenn...@gmail.com, Oct 23, 2008

While attempting to use UseMon? wiht JBoss4.2.2 I get an OutofMemory? Exception.

JBoss Bootstrap Environment
JBOSS_HOME: C:\programming\java\jboss-4.2.2.GA
JAVA: C:\programming\java\jdk1.5.0_16\bin\java
JAVA_OPTS: -javaagent:C:\programming\java\usemon-distro-1.0-SNAPSHOT\usemon-a

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

CLASSPATH: C:\programming\java\jdk1.5.0_16\lib\tools.jar;C:\programming\java\j

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

Comment by drgbenn...@gmail.com, Oct 23, 2008

sorry about the last comment. I rebooted the machine and I was able to start JBOSS fine following same steps as w...@bill.ee.

Comment by drgbenn...@gmail.com, Oct 27, 2008

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!

Comment by mats.kar...@gmail.com, Nov 5, 2008

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

Comment by shautv...@gmail.com, Nov 17, 2008

i cannot find where to put database user/password for the collector

Comment by shautv...@gmail.com, Nov 17, 2008

a policy file with an AllPermission??...that would not be allowed even in our development environment.

Comment by shautv...@gmail.com, Nov 17, 2008

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

Comment by davyfen...@gmail.com, Dec 16, 2008

Any one have ever tried to use usemon under windows? Or any one could post the steps of how to do this please? thanks!

Comment by sreedhar...@genpact.com, Feb 11, 2009

Can this be used under tomcat server. Will this support Tomcat Load balanced using mod_JK

Comment by michal.g...@gmail.com, Apr 9, 2009

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??

Comment by MrSmile...@gmail.com, May 26, 2009

Can this be configured against any other databases then MySQL.

Comment by kks...@gmail.com, Jun 9, 2009

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 .

Comment by kks...@gmail.com, Jun 10, 2009

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


Sign in to add a comment
Powered by Google Project Hosting