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.

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. See Downloading the agent.
URL/IP of the SixthSense collector (your tenant URL which will be provided by Customer Support).
SIXTHSENSE_TOKEN - For accessing the token, see Accessing your Access Token under Getting started with the Observability Portal.

note

The agent uses internet to communicate with backend address. For more information, see Enabling proxy.

Agent download requisites

Variables	About
TOKEN	To download the agent, an access token is required from Customer Support.
AGENT_VERSION	By default use "latest".

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 for Java 7 agent.

To download the agent, perform the following procedure:

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

export AGENT_VERSION="latest"
{
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"

}

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 and then restart 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/Config/agent.config file.

note

Ensure that you provide same permissions (user and group) to the agent folder with which the application is running. Also, copy the agent folder in the application's parent directory.

Adding application information in the agent.config file

Add application name and team_id.
Set “agent.service_name” to identify your application name in the dashboard.

For example, assume USER_APP is your application name. Navigate to agent.config file i.e. Agent folder/Config/agent.config file and update.

The service name in UI

agent.service_name=${SW_AGENT_NAME:Your_ApplicationName}

For OneCloud Platform use the following command:

set SW_AGENT_FORCE_TLS as false in the agent.config file.

Get Access Token from the SixthSense portal. See Accessing your Access Token under Getting started with the Observability Portal.

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

Update the backend collector URL

Set collector.backend_service with Backend Collector URL.

Example

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

For OneCloud Platform use the following parameters:

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

Instrumenting an application

note

The agent uses internet to send data to the backend service. If direct internet access is not enabled, please pass a proxy through which it can communicate to our backend address.

Enabling proxy

Enable proxy using any of the following two methods:

Set proxy at system/container level.

Example:

1 a. Windows Servers:

add environment variable in system level variables for HTTP_PROXY, GRPC_PROXY_EXP  
               

1 b. Linux Servers:

Add proxy in the ~/.bashrc file as follows: 

export HTTP_PROXY= 10.0.0.1:3128 && export GRPC_PROXY_EXP=10.0.0.1:3128 

Pass Proxy to JVM by adding proxy in Java options.

JAVA_OPTS= -Dhttp.proxyHost=ip_address -Dhttp.proxyPort=3128 -Dhttps.proxyHost=ip_address -Dhttps.proxyPort=3128

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

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

note

For Windows based applications, if the arguments to the application are being passed from windows registry service, then you must pass the agent in those arguments in order to integrate the agent.

Integrating agent 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 Instrumenting an application.
Integrate the agent with the Dockerfile.

Add the following commands:

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
 
ENV SW_AGENT_NAME=Your_app_name
ENV SW_AGENT_COLLECTOR_BACKEND_SERVICES=grpc-collector-observability.sixthsense.rakuten.com:443
ENV SW_AGENT_AUTHENTICATION=token_from_settings_section_in_sixthsense_ui

 
WORKDIR /app
COPY --from=builder /app .
 
EXPOSE 9555
ENTRYPOINT java -javaagent:/opt/agent/sixthsense-agent.jar -jar /app/payments.jar 

To build the docker image, 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 

#Prerequisites

note

#Downloading the agent

#Set up the agent

note

#Adding application information in the agent.config file

#Instrumenting an application

note

#Enabling proxy

#Add -javaagent flag

note

#Integrating agent in a docker environment

Prerequisites

Downloading the agent

Set up the agent

Adding application information in the agent.config file

Instrumenting an application

Enabling proxy

Add -javaagent flag

Integrating agent in a docker environment