Installing APM agent

Installing Java Agent

The Java agent collects detailed performance metrics about applications and the computing environment as transactions are executed. The Java agent collects this information from applications and resources running on Java Virtual Machines (JVMs) and sends the information to the SixthSense platform. It then processes and stores the data for real-time and historical reporting. You can view and work with the collected data using the user interface to create alerts or take responsive action. The Java agent inserts probes into the classes bytecode of the instrumented application. Inserting the probes into the bytecode is part of the instrumentation process that enables the monitoring of your applications. After the application is instrumented, the Java agent starts collecting the data.

For java application monitoring,

• Deploy agents to monitor the performance and availability of application servers.
• Test, adjust, and optimize monitoring of application components.
• The agent uses some of the application server Java heap memory to store collected data.
• For a highly utilized heap java application, increase the heap allocation on the installation of the Java agent.
• If there are large numbers of transaction traces, increase the JVM heap size.

Prerequisites

Configuration requisites

• For prerequisite checks for agent installation, see Prerequisite checks for agent installation.
• SixthSense Java Agent Downloading the agent.
• Url/IP of the SixthSense collector (your tenant URL which will be provided by the onboarding team)
• Access token from the SixthSense portal. For accessing the token, see Accessing your access toke

Agent download requisites

Variables	About
TOKEN	To download the agent, an access token is required from the onboarding team
AGENT_VERSION	SixthSense Agent Version

Agent Configuration

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

Downloading the agent

Prerequisites for downloading the agent

• Private Token from the onboarding team
• Link to download a specific version

To download the agent, perform the following procedure:

1. Ensure there is ingress from the internet/ from the SixthSense enabled.
2. Download the agent using curl. If the agent is downloaded to Docker, install curl before proceeding.

{

curl --header "PRIVATE-TOKEN: ${TOKEN}" --output agent.zip "https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/4/packages/generic/sixthsense/${AGENT_VERSION}/sixthsense.zip"

}

Set up the agent

Configure the application server that needs instrumenting to include the path to the agent primary .jar file (i.e. sixthsense-agent.jar). Configure the path by editing the application server startup script, then restarting the application server. When the application server restarts, the Java Agent instruments the classes discovered for default components of the JVM and application environment. The specific steps that are involved depend on the application server.

• Unzip the downloaded Agent (See, Downloading the agent.).
• Navigate to agent.config file i.e. Agent folder/SixthSense/Config/agent.config file

Adding application information in the agent.config file

• Add application name and team_id.

• Set “agent.service_name” to identify your application name and the team id to identify which team your application belongs to “agent.team_id” in the dashboard.

Example: Assume USER_APP is your application name. Navigate to agent.config file i.e. Agent folder/SixthSense/Config/agent.config file and update.

# The service name in UI

agent.service_name=${SW_AGENT_NAME:Your_ApplicationName}

Get Access Token from the SixthSense portal

• Login to the SixthSense portal.
• Go to Settings on the left pane.
• Click Access token.
• Click Show access token.
• Click Copy to copy the access token.
• Navigate to agent.config file Agent folder/SixthSense/Config/agent.config file.
• Add to property set agent.authentication in the agent.config file.

agent.authentication = ${SW_AGENT_AUTHENTICATION: <AccessToken>}

Update the backend collector URL

1. Set collector.backend_service with Backend Collector URL

collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:stg-http-collector-observability.sixthsense.rakuten.com:443}

For OneCloud Platform use the following command:

collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:133.237.176.44:80}

Instrumenting Application

Add -javaagent flag

• After completing Agent configuration, while starting your application, add the JVM flag -javaagent:Path to sixthsense-agent.jar under the startup/entrypoint application file.

Example to run the Java Agent for a standalone application

• Execute the Java Agent command along with your Jar File. For example, if your application jar is named as "java_backend", use the following command.

java -javaagent:{Path to SixthSense Agent Jar File →> /opt/sixthsense/sixthsense-agent.jar} -jar {Path to your Jar File}

Steps for Agent Integrations in a docker environment

• Download the SixthSense Agent (See, Downloading the agent.)
• After downloading the agent follow the procedure in Adding application information in the agent.config file.
• Setup the agent configurations as mentioned in the Instrumenting Application section.
• Integrate the agent with the Dockerfile.

Add the following command:

COPY agent agent/

ENTRYPOINT java -javaagent:/agent/sixthsense-agent.jar -jar your_application.jar

• Build your Docker images.
• Run your application with the Docker image created.
• On the dashboard, you will see the application name defined above.

Example for Docker

# docker build -t adservice .

FROM openjdk:8-slim as builder

WORKDIR /app

COPY ["build.gradle", "gradlew", "./"]

COPY gradle gradle

RUN chmod +x gradlew

RUN ./gradlew downloadRepos

COPY . .

RUN chmod +x gradlew

RUN ./gradlew installDist

FROM openjdk:8-slim

# Download curl

RUN apt-get -y update && apt-get install -qqy && apt-get install -y curl && apt-get install -y unzip \

wget \

&& rm -rf /var/lib/apt/lists/*

# Here we are downloading the agent at runtime

# Sixthsense Agent

ARG TOKEN

ARG AGENT_VERSION

RUN mkdir -p /opt/sixthsense && \

curl -v --header "PRIVATE-TOKEN: ${TOKEN}" --output /opt/sixthsense/agent.zip "https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/4/packages/generic/sixthsense/${AGENT_VERSION}/agent.zip" && \

unzip /opt/sixthsense/agent.zip -d /opt/sixthsense && \

rm -rf /opt/sixthsense/agent.zip

COPY agent.config /opt/sixthsense/agent/config/agent.config

WORKDIR /app

COPY --from=builder /app .

EXPOSE 9555

ENTRYPOINT ["/app/build/install/hipstershop/bin/AdService"]

To build the docker image, the variables are passed as build arguments i.e AGENT_VERSION and TOKEN.

docker build --build-arg AGENT_VERSION=v1.1 --build-arg TOKEN=token_from_onboarding adservice:v1

Configuring JavaAgent for Tomcat Server

You can configure java agent by passing arguments through 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

• Extract the downloaded SixthSense Java Agent zip file on the server where the application must be monitored.

Prerequisites

• SixthSense Java Agent. (See Downloading the agent)
• SSL/TLS Certificates for authentication (For Agent to connect to SixthSense platform, these certificates will be provided by onboarding team).
• Url/IP of the SixthSense collector (Your tenant url which will be provided by the onboarding team)
• Access token from the SixthSense UI (See, How to connect to the Agent SixthSense Portal)

Adding application information in the Agent config 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

The specific steps that are involved depend on the application server.

• unzip and create the folder named as “ca” in the agent/ca path 
• copy the ca.crt files shared to the agent/ca folder 
• Add application name and team_id , 
• 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 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 example:

collector.backend_service=${SW_AGENT_COLLECTOR_BACKEND_SERVICES:133.237.176.44:80}

Unix Environments

• 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 agent configuration, 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 Agent configuration, 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 agent configuration, restart Tomcat to start monitoring.

catalina.bat

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

Configure Java Agent through 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.