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.
• For supported agent versions and framework, see APM agents.

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	Version 1.20.0.

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:

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

export AGENT_VERSION="1.20.0"

curl --header "PRIVATE-TOKEN:<TOKEN>" --output agent-v1.20.0.zip "https://artifacts-observability.sixthsense.rakuten.com/api/v4/projects/4/packages/generic/sixthsense/v1.20.0/agent-v1.20.0.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

1. Add application name and team_id.
2. 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 agent.force_tls=${SW_AGENT_FORCE_TLS:false} in the agent.config file.

3. 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:

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

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:

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

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

ENV SW_AGENT_FORCE_TLS=false in dockerfile for onecloud

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

For log trace correlation, see Log trace correlation.