UsageJInsightAgent

Instrumenting a JVM with JInsight Java Agent is refreshingly simple:

1. Add the javaagent option to your java command line like so: -javaagent:/usr/share/java/jinsight.jar
2. Configure the agent properties like reporter type, global tags etc.
3. (Re)start your JVM

Once the JVM is launched, the agent starts reporting a wide array of metrics, that give you unparalleled insight into various subsystems in your process.

A. Installing the JInsight Java Agent

Download the agent

Download the latest jinsight-X-X-X.jar from the Releases Page and save it to /var/lib/jinsight/ folder. Optionally, link jinsight-latest.jar to jinsight-X-X-X.jar

Configure the agent

JInsight currently supports two reporters: Apptuit (default) and Prometheus. The Apptuit reporter directly sends the metrics to Apptuit using Apptuit API. The Prometheus reporter exposes the metrics in Prometheus exposition format.

Below are sample configurations for these reporters. Refer to the Configuration Options section below for complete list of options.

Sample config for Apptuit Reporter

Create a config file:

mkdir /etc/jinsight/
cat > /etc/jinsight/jinsight-config.properties  << EOF
reporter=APPTUIT
apptuit.access_token=YOUR_APPTUIT_ACCESS_TOKEN
global_tags=env:dev, dev:rajiv, agent:jinsight
EOF

Edit the access_token and global_tags options (see below)

Sample config for Prometheus reporter

Create a config file:

mkdir /etc/jinsight/
cat > /etc/jinsight/jinsight-config.properties  << EOF
reporter=PROMETHEUS
global_tags=env:dev, dev:rajiv, agent:jinsight
EOF

Add JInsight agent to JVM launch command

The JVM launch command needs to be updated to include javaagent and jinsight.config parameters. The steps to add these are slightly different for Tomcat/Jetty etc.

Setting up generic Java processes

Update your Java command line to include javaagent and jinsight.config parameters like so:

java -javaagent:/var/lib/jinsight/jinsight-latest.jar -Djinsight.config=/etc/jinsight/jinsight-config.properties -cp helloworld.jar HelloWorld

Setting up Tomcat

Tomcat installed from .rpm

Update JAVA_OPTS to include the java agent on Tomcat's startup

vi /usr/share/tomcat/conf/tomcat.conf
JAVA_OPTS="-javaagent:/usr/share/java/jinsight.jar -Djinsight.config=/etc/jinsight/jinsight-config.properties"

Other Tomcat installations

Update CATALINA_OPTS to include the java agent on Tomcat's startup

cat >> /usr/share/tomcat8/bin/setenv.sh  
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:/usr/share/java/jinsight.jar -Djinsight.config=/etc/jinsight/jinsight-config.properties"

Verify the path to the jar and properties in the above command. Also make sure the Tomcat process has read access to these files.

Setting up Jetty

Update JAVA_OPTIONS to include the java agent on Jetty's startup

vi jetty.sh

add the line:

JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/usr/share/java/jinsight.jar -Djinsight.config=/etc/jinsight/jinsight-config.properties"

Verify the path to the jar and properties in the above command. Also make sure the Jetty process has read access to these files.

B. Configuration Options

The agent loads the configuration options from /etc/jinsight/jinsight-config.properties or ${USER_HOME}/.jinsight/jinsight-config.properties file it exists. The agent can be forced to load the configuration from a different location by setting the system property jinsight.config. For example: -Djinsight.config=/etc/jinsight/jinsight-config.properties

Common properties (for all reporters)

reporter

Currently two reporters are supported: APPTUIT (default) or PROMETHEUS
Example: reporter=APPTUIT or reporter=PROMETHEUS

global_tags

Comma separated tag value pairs that are added to all the metrics generated by the agent.
Example: global_tags=dc:us-east, env:prod

reporting_frequency

The frequency at which to report the metrics that have been collected. The format for this property is "nHnMn.nS" where the suffix H marks hours, M marks minutes, S marks seconds. The suffixes (H/M/S) can be upper or lower case.
Example: reporting_frequency=60s or reporting_frequency=2m or reporting_frequency=1m15s Default: 15s

Apptuit Reporter specific properties

The following additional properties are available when using the Apptuit reporter

apptuit.access_token

The Access Token to be used by the agent for uploading data to your account.
Example: apptuit.access_token=YOUR_APPTUIT_ACCESS_TOKEN

Prometheus Reporter specific properties

The following additional properties are available when using the Prometheus reporter

prometheus.exporter_port

The port on which Prometheus exporter metrics will be accessible. Default: 9404
Example: prometheus.exporter_port=9404

prometheus.exporter_endpoint

The url path at which the Prometheus exporter metrics will be accessible. Default: /metrics
Example: prometheus.exporter_endpoint="/metrics"

Graphite/Grafana Reporter

Currently unsupported