Java agent for Tomcat server

Prerequisites

  • SixthSense Java Agent. See, Downloading the agent.
  • SSL/TLS certificates for authentication required for agents to connect to SixthSense platform. These certificates will be provided by Customer Support).
  • URL/IP of the SixthSense collector (your tenant URL which will be provided by Customer Support).
  • Access token. For accessing the token, see Accessing your Access Token.

Configuring the agent

You can configure the Java agent by passing arguments through the environment variables. Pass the environment variables from different locations of Tomcat server as follows.

You must edit the Tomcat startup script. By default, the Tomcat startup script is catalina.sh or catalina.bat in the  $CATALINA_HOME/bin directory or set the arguments in the environment variables of Tomcat.

Downloading the agent

To monitor any java application, you need valid licenses and access to download the SixthSense Java Agent.

curl --header "PRIVATE-TOKEN:{{TOKEN}}" --output agent.zip "https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/4/packages/generic/sixthsense/{{AGENT_VERSION}}/agent.zip"
  • Extract the downloaded SixthSense Java Agent zip file on the server where the application must be monitored.

Adding application information in the agent configuration file

Configure the application server that needs instrumenting to include the path to the agent primary .jar file (SixthSenseAgent.jar).

  1. Configure the path by editing the application server startup script.
  2. Restart the application server.
  3. When the application server restarts, the Java Agent instruments the classes discovered for default components of the JVM and application environment.
note

Specific steps that are involved depend on the application server.

  1. Unzip and create the folder named as “ca” in the agent/ca path.
  2. Copy the ca.crt files shared to the agent/ca folder.
  3. Add application name and the team_id.
  4. Set “agent.service_name” to identify your application name and team id to identify which team your application belongs to “agent.team_id” in the dashboard.

For example, assume USER_APP is your application name. Navigate to the agent folder /SixthSense/Config/agent.config file.

agent.service_name=${SW_AGENT_NAME:USER_APP}

Connecting to the agent SixthSense portal

  1. Login to your SixthSense portal
  2. Click Settings on the left pane.
  3. Click Access token.
  4. Click Show access token.
  5. Click Copy to copy the access token and add to property set agent.authentication in the Agent.config file
  6. Navigate to agent.config file  Agent folder/SixthSense/Config/agent.config file*
    Set agent.authentication = ${SW_AGENT_AUTHENTICATION: AccessToken}
  7. Set collector.backend_service with Backend Collector URL which is provided by the onboarding team.

Example: collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:d-c.34.93.18.45.sslip.io:443}

Unix Environment

setenv.sh

  1. Create a CATALINA_BASE/bin/setenv.sh script if one doesn't already exist. 
  2. Configure your setenv.sh script to use the SixthSense agent using the CATALINA_OPTS environment variable: export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/full/path/to/SixthSense.jar.
  3. After configuring the agent, restart Tomcat.

catalina.sh

  1. Configure your catalina.sh file to use the SixthSense agent using the JAVA_OPTS environment variable: export JAVA_OPTS="$JAVA_OPTS -javaagent:/full/path/to/SixthSense.jar".
  2. After configuring the agent, restart Tomcat to start monitoring.

Windows Environment

setenv.bat

  1. Create a CATALINA_BASE/bin/setenv.bat script if one doesn't already exist. 
  2. Configure your setenv.bat script to use the SixthSense agent using the CATALINA_OPTS environment variable: SET "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:/full/path/to/SixthSense.jar".
  3. After configuring the agent, restart Tomcat to start monitoring.

catalina.bat

  1. If you use catalina.bat to launch Tomcat, set the Java_OPTS variable at the top of the SET Java_OPTS=%Java_OPTS% -Javaagent:/full/path/to/SixthSense.jar file.
  2. After configuring the agent, restart Tomcat to start monitoring.

Configuring Java agent through a service

  1. Navigate to Start > Apache Tomcat X.Y.Z. > Configure Tomcat > Java.
  2. In the Java Options text box, enter the following argument. Use forward slashes '/' for the path separator.
    SET "CATALINA_OPTS=%CATALINA_OPTS% -javaagent:/full/path/to/SixthSense.jar"
  3. For Tomcat 6, add a line break after the -Javaagent argument -Javaagent:/full/path/to/SixthSense.jar
  4. Select Apply and restart Tomcat to start monitoring.