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

  • 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

VariablesAbout
TOKENTo download the agent, an access token is required from Customer Support.
AGENT_VERSIONSixthSense 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}/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/SixthSense/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

  1. Add application name and team_id.
  2. Set “agent.service_name” to identify your application name and the team id to identify which team your application belongs to i.e. “agent.team_id” in the dashboard.

For 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}

For enabling connectivity to OneCloud collector, Set SW_AGENT_FORCE_TLS as false in the agent.config file.

SW_AGENT_FORCE_TLS: false
  1. 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

  1. Set collector.backend_service with Backend Collector URL.
  2. Customer Support will provide the Backend Collector URL

Example

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

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:

  1. Set proxy at system/container level.

Example:

a. Windows Servers: add environment variable in system level variables for HTTP_PROXY, GRPC_PROXY_EXP

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
  1. 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

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}

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

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
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, 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