Installing the Java Agent for Tomcat

Background

The tCell Java Agent is implemented as a Java agent. The package includes a agent JAR file which will embed within the application server at startup time to instrument the code. The package is provided as an archive file that is unpacked on the same server as your application server.

 

Prerequisites

Before you can install the agent, you need to have the following:

  • A tCell account setup
  • An Application Created (Admin>Applications)
  • Tomcat version 7 or later
  • Java version 7 or later
  • Allow outbound HTTPS connections to the tCell cloud: What IPs do tCell agents connect to?

 

Installation - Get the Config File

  1. Click on "Admin" in top nav bar
  2. Click "Download Agent"
  3. Select "Java" agent
  4. Download either the zip or the tar.gz file as desired
  5. Select "Create New API Key" (default)
  6. Click "Download Config File" to download the agent's config file (which is prepopulated with the application and key information)

Installation - Install the JavaAgent

  1. Unpack the Java Agent in the parent of the directory you'd like to use for tCell.

    If using the standard Tomcat directory structure, we recommend using the Tomcat home directory, e.g. "./apache-tomcat-7.0.63/".

    You should now have a directory "tcell"

  2. Copy the file tcell_agent.config to this directory
  3. Verify permissions on the tcell directory and files. The user your application server runs as should be able to read and write to this directory. For example:

    chown -R tomcat:tomcat ./tcell

  4. Note that in the tcell directory, there is a file called "tcellagent.jar". Update your Tomcat startup command line to have the following:

    >"-javaagent:<path including filename to tcellagent.jar>"

    On vanilla Tomcat installations, this can be configured by editing or creating the bin/setenv.sh file to have the "-javagent" argument added to CATALINA_OPTS.

    For example, if you installed tCell in $CATALINA_HOME, you can add:

    CATALINA_OPTS="$CATALINA_OPTS -javaagent:${CATALINA_HOME}/tcell/tcellagent.jar"

  5. Restart your application server

 

Verification

If everything is working, you should see on the Server Agents side bar menu an "UP" value that is non-zero (depending on how many server agents you have installed).

 

Troubleshooting

Log files can be found in tcell/log directory.

Log level can be customized in tcell_agent.config file by adding a block such as the following

      "logging_options": {
           "enabled":true,
           "level":"INFO"
           }

Valid levels are: DEBUG, INFO, WARN, ERROR. (INFO is the default) In the tcell directory, see tcell_agent.config.template for an example.

If you do not see a tcell/log directory, it is likely that the tCell agent did not start. If so

  1. Verify that the tCell agent is being added to the server startup:

    michaelfeiertag$ ps aux | grep --color tcell
    michaelfeiertag 23696 1.4 0.0 2452244 792 s000 S+ 12:19PM 0:00.01 grep --color tcell
    michaelfeiertag 20617 0.1 0.2 4968308 20468 s002 U Thu03PM 3:16.72 /Library/Java/JavaVirtualMachines/jdk1.7.0_71.jdk/Contents/Home/bin/java -javaagent:/Users/michaelfeiertag/dev/tomcat/apache-tomcat-7.0.63/tcell/tcellagent.jar -classpath /Users/michaelfeiertag/dev/tomcat/apache-tomcat-7.0.63/bin/bootstrap.jar:/Users/michaelfeiertag/dev/tomcat/apache-tomcat-7.0.63/bin/tomcat-juli.jar -Dcatalina.base=/Users/michaelfeiertag/dev/tomcat/apache-tomcat-7.0.63 -Dcatalina.home=/Users/michaelfeiertag/dev/tomcat/apache-tomcat-7.0.63 org.apache.catalina.startup.Bootstrap start

  2. Check for errors in your catalina.out log 
Have more questions? Submit a request

Comments