Java

Supported Platforms

Operating systems: OS X, Linux, Windows Architectures: x86-64 (x64) only

Prerequisites

• A tCell account setup
• An application created (Admin > Applications)
• Allow outbound HTTPS connections to the tCell cloud: What IPs do tCell agents connect to?
• On Windows: Download and install the Visual C++ 2015 runtime: https://www.microsoft.com/en-us/download/details.aspx?id=53840
• Download the agent and the config file:
  1. Click on "tCell Admin" in top nav bar
  2. Click "Download Agent"
  3. Select "Java" agent
  4. Download either the zip or the tar.gz file
  5. Select "Create New API Key" (default)
  6. Click "Download Config File" to download the agent's config file (which is pre-populated with the application and API key information)

Installation

Install into a typical Apache Tomcat server

These steps are appropriate for a typical Tomcat installation, as acquired from the upstream source http://tomcat.apache.org

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 called tcell
2. Copy the file tcell_agent.config to this directory.
3. Verify permissions on the tcell directory and files. The user that your application server runs as should be able to read and write to this directory. However, all JAR files should be owned by root and read only, to minimize the chance of a compromised user replacing a JAR. For example:

 
1
chown -R tomcat:tomcat ./tcell
2
chmod u+rwx ./tcell
3
chown root:tomcat ./tcell/tcell*jar
4
chmod 444 ./tcell/tcell*jar

4. 1. On vanilla Tomcat installations, edit or create the bin/setenv.sh file (setenv.bat on Windows) to have the -javagent argument added to CATALINA_OPTS.

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

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

   Windows equivalent:

    
   1
   set CATALINA_OPTS=%CATALINA_OPTS% "-javaagent:%CATALINA_HOME%\tcell\tcellagent.jar"

   JAVA_HOME and JRE_HOME Environment Variables

   Running the tomcat server requires one of these to be set. This is usually part of the normal Java installation process. The server will not start without a valid Java installation.

2. If you start your application via command line update it to have the following:

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

   Note: that in the tcell directory, there is a file called "tcellagent.jar".

5. Restart your application server

Install into a Red Hat / Centos packaged Tomcat server

These steps are appropriate when using a Red Hat derived distribution's tomcat package.

1. If not already installed, install the package using OS tools such as yum install tomcat or dnf install tomcat.
2. Unpack the Java Agent into the tomcat directory /usr/share/tomcat creating the new directory /usr/share/tomcat/tcell.
3. Copy or move the downloaded tcell_agent.config file to this new directory.
4. Ensure that the files and directories created or added by steps 2 and 3 will be readable by the 'tomcat' user. For example:

    
   1
   chown -R tomcat:tomcat /usr/share/tomcat/tcell

5. Add the java agent option to the end of /etc/tomcat/tomcat.conf

    
   1
   CATALINA_OPTS="$CATALINA_OPTS -javaagent:/usr/share/tomcat/tcell/tcellagent.jar"

6. Restart the tomcat server.

Verification

To verify that data is being sent to tCell go to your tCell console and ensure that the number of app server agents listed for the application you just created is more than 0.

Troubleshooting

Try the test command:

 
1
$ java -jar tcell/tcellagent.jar test
2
Checking config file present                                            [PASSED]
3
Checking config file can be parsed                                      [PASSED]
4
Checking environment parameters starting with TCELL_                    [PASSED]
5
Initializing logging                                                    [PASSED]
6
Checking for app_id                                          your-appid
7
Checking for api_key                                                    [PASSED]
8
Fetching policy from API                                                [PASSED]
9
Sending events to input                                                 [PASSED]
10
Checking libtcellagent version:                                          [1.0.0]

YourKit profiler compatibility

Make sure the tCell agent java argument is listed before the Yourkit argument.

FileNotFoundException (Wildfly)

You may see something similar to the stack trace in this section. The warnings are benign. You can disable the instrumentation that produces this exception by adding

"enabled_instrumentations": {"jboss": false }

to your application block in tcell_agent.config, but this may lead to missing packages in the tCell UI.

 
1
2020-07-23T03:10:05.503499332-04:00 [1.12.2-SNAPSHOT-20200720-GETWELL 9505 unnamed] tCell-client WARN io.tcell.PackageTracker - Failed to collect package info for code source ca.uhn.hapi-hapi-structures-v21-2.3.jar
2
java.nio.file.NoSuchFileException: /opt/gwn/wildfly-16.0.0.Final/standalone/deployments/lib/ca.uhn.hapi-hapi-structures-v21-2.3.jar
3
        at sun.nio.fs.UnixException.translateToIOException(UnixException.java:86)
4
        at sun.nio.fs.UnixException.rethrowAsIOException(UnixException.java:102)
5
        at sun.nio.fs.UnixException.rethrowAsIOException(UnixException.java:107)
6
        at sun.nio.fs.UnixFileSystemProvider.newByteChannel(UnixFileSystemProvider.java:214)
7
        at java.nio.file.Files.newByteChannel(Files.java:361)
8
        at java.nio.file.Files.newByteChannel(Files.java:407)
9
        at java.nio.file.Files.readAllBytes(Files.java:3152)
10
        at io.tcell.PackageTracker.computeSha1Sum(PackageTracker.java:130)
11
        at io.tcell.PackageTracker.loadPackageInfo(PackageTracker.java:104)
12
        at io.tcell.PackageTracker.run(PackageTracker.java:55)
13
        at java.lang.Thread.run(Thread.java:748)

Logging

Log files can be found in the tcell/logs directory. If you do not see a tcell/logs 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 by running the following command:

    
   1
   ps aux | grep --color tcell

2. Check for errors in your catalina.out log. Alternatively, running bin/catalina.sh run or bin/catalina.bat run on Windows will start tomcat in the foreground, and print any errors while starting up.

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

json
1
"logging_options": {
2
    "enabled": true,
3
    "level": "INFO"
4
}

Valid log levels are:

• ERROR
• WARN
• INFO (default)
• DEBUG
• TRACE

The list indicates the precedence among the levels, from top to bottom. When you enable a log level, the higher log levels are also enabled. For example, if you enable WARN, then ERROR is also enabled. In the tcell directory, see tcell_agent.config.template for an example.

When a log file becomes full, logging continues in a new log file. See Log Rolling for more information.