Java agent for Tomcat server

Prerequisites

  • For prerequisite checks for agent installation, see Prerequisite checks for agent installation.
  • SixthSense Java Agent. See, Downloading the agent.
  • For supported agent versions and framework, see APM agents.
  • 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.

Downloading the agent version 1.18.4 (latest)

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

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

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.

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}

For OneCloud Platform use the following steps:

  1. Set collector.backend_service with Backend Collector URL as follows:

For connectivity to backend using intra public network: collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:133.237.176.44:80}

For connectivity to backend using onecloud private network: collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:100.99.116.221:80}

  1. Set TLS to false in the agent configuration file agent.force_tls=${SW_AGENT_FORCE_TLS:false}

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-agent.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-agent.jar".
note

If you are using Java version 17 and above, use JDK_JAVA_OPTIONS or JAVA_TOOL_OPTIONS instead of JAVA_OPTS.

  1. 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-agent.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-agent.jar file.
note

If you are using Java version 17 and above, use JDK_JAVA_OPTIONS or JAVA_TOOL_OPTIONS instead of JAVA_OPTS.

  1. 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-agent.jar"
  3. For Tomcat 6, add a line break after the -Javaagent argument -Javaagent:/full/path/to/sixthsense-agent.jar
  4. Select Apply and restart Tomcat to start monitoring.