Welcome

With the release of Java 9, a decision has been made to pull the free Satoris 2.7 Community Edition from the site. Satoris 2.8, available to clients, supports Java 8 and onwards, with full Java 9 compatibility and module integration coming in version 2.9 expected to be released end of 2017. The following content is made available for those who have previously downloaded Satoris 2.7.

Changes in 2.7.2

  • Resolved issue with the -generate-aj-bundle console command in the generation of an instrumentation pointcut definition for a method overloaded in subclasses
  • Added new option, --non-managed, to the -generate-aj-bundle console command to restrict instrumentation to only those probes with both hotspot and !managed labels

Changes in 2.7.1

  • Renamed the /bundle directory, containing the satoris-javaagent.jar library, to /agent
  • Added /api directory containing the classes, sources, and javadoc for the Probes Open API
  • New implementation of the Environment interface with better performance and lower memory footprint
  • New current metering extension provider offering access to the name of the current active probe via the Environment interface

Platform Support

Whilst the source code for both the Satoris agent and console target 1.6 Java runtimes the above distribution has been compiled to target 1.7 and greater Java runtimes. Java 9 is currently not supported.

Most testing and usage is on Linux and Mac OS X but both agent and console should run equally well on Microsoft Windows.

Agent Installation

Satoris is extremely easy to setup – it should only take a matter of minutes to gain performance insights. The metering runtime is an adaptive system, much like the JVM Hotspot technology, so it’s highly recommended that any application profiled is made to execute performance critical code paths a number of times. The longer an application executes under representative workload the more relevant and accurate the results will be.

To instrument a codebase with the JVM instrumentation agent add the following to the command line of the process:

-javaagent:/opt/satoris-${version}/agent/satoris-javaagent.jar -noverify

On Windows add the agent as follows:

-javaagent:c:\satoris-${version}\agent\satoris-javaagent.jar -noverify

The agent library does not need to be added to the classpath of the application. We highly recommend that this is not done unless both file paths resolve equivalently.

Console Launch

Satoris ships with a Java monitoring client application for real-time metering observation. The client application jar can be found in the /console directory of the installation. To start the client simply execute

java -jar satoris.jar

The memory assigned to the client console can be increased by adding -Xmx to the command line.

java -Xmx256M -jar satoris.jar

To use an alternative font use the jxinsight.console.font system property as follows:

java -Djxinsight.console.font="Open Sans" -jar satoris.jar

To connect to an instrumented runtime mount the server via the menu sequence Console -> Add Server. The default port for an agent is 1515 unless changed within the configuration. If the default port is already taken by another process such as instrumented runtime the agent will increment the port and try binding again.

Agent Configuration

Whilst many of the metering extensions ship with default settings suitable for most applications it is possible to change these using a jxinsight.override.config file, which by default is searched for within the working directory of the executing process. The location can be changed with the system property -Djxinsight.home=<path-to-config-dir>.

The most common setting to be overridden is the hotspot metering extension threshold. To change the threshold to 5 simply add the following line to the config file.

j.s.p.hotspot.threshold=5

To change the port used by the console metering extension from 1515 to 2525 add the line.

j.s.p.console.reactor.port=2525

The distribution includes example configurations for Apache Kafka and Apache Cassandra. To use such configurations set the jxinsight.home property as follows:

-Djxinsight.home=/opt/satoris-${version}/conf/apache-kafka
-Djxinsight.home=/opt/satoris-${version}/conf/apache-cassandra

Video Walkthrough

Agent Instrumentation

Instrumentation filters are listed in the file jxinsight.aspectj.filters.config, which by default is assumed to be located in the working directory of the executing process. The location can be changed with the system property -Djxinsight.home=<path-to-config-dir>.

If no file is found then some default filters are applied that exclude code in many common open source frameworks. It is strongly recommended that this file be created and listing the common root package(s) of an application. For example to limit instrumentation to the com.acme package and its sub-packages add the following line:

com.acme.

A line not starting with [!, / ,*, =, #, [] represents a class name prefix inclusion condition.

# include *only* those classes within "com.acme."
com.acme.

A line starting with ! negates the condition specified following the ! character.

# include all classes except those prefixed with "com.bea."
!com.bea.

Exclusions have higher precedence over inclusions.

# include classes prefixed with "org.jboss" except for "org.jboss.seam"
org.jboss.
!org.jboss.seam.

A condition starting with * character represents a class name suffix condition.

# include only those classes ending with "Factory"
*Factory
# include all classes except those ending with "Factory"
!*Factory

A condition starting with the / character represents a class name substring condition.

# include only those classes containing ".jdbc."
/.jdbc.
# include all classes except those containing ".jdbc."
!/.jdbc.

A condition starting with the = represents a class name exact match condition.

# include the acme.HelloWorld class ignoring inner classes or classes nested in a same named package
=acme.HelloWorld
# exclude the acme.HelloWorld class ignoring inner classes or classes nested in a same named package
!=acme.HelloWorld

A condition starting with [ represents a class bytecode contains match

# include any class which contains "Ljava/util/logging/Logger" in its bytecode
[Ljava/util/logging/Logger

Agent Limitations

The current agent will not instrument classes on the bootclasspath including all standard Java runtime libraries.

The agent will not instrument classes loaded by the following Classloader classes:

sun.reflect.DelegatingClassLoader
org.apache.cxf.common.util.ASMHelper$TypeHelperClassLoader

The agent will not instrument classes within the following packages:

com.newrelic
com.dynatrace
com.jloadtrace
com.appdynamics
com.singularity
com.jinspired
org.jinspired
org.apache.log4j
org.slf4j

The agent will not instrument classes containing the following strings:

$JaxbAccessor
jaxws_asm
CGLIB$$
_$$_javassist_

Metering Extensions

The Satoris metering engine uses extensions to increase its data collection capabilities, intelligently adapt measurement, record and playback measured behavior, simulate in near real-time behavior across an entire distributed system as well as take control of the execution flow for improved quality of service (QoS) and resilience. A metering extension provider does not create probes but instead augments (decorates) measurement probes with additional optional capabilities as well as disabling further measurement of the probe as is the case with the hotspot metering extension, enabled by default.

A metering extension provider is enabled using the following system property pattern.

-Djxinsight.server.probes.${provider}.enabled=true

Most providers require other system properties to be set, so it is best to create a jxinsight.override.config file and add the above as follows:

jxinsight.server.probes.${provider}.enabled=true

A short form of the above property is also possible when using the config file.

j.s.p.${provider}.enabled=true

Filtering

A metering extension provider can have its augmentation restricted to a particular set of probes using filtering.

j.s.p.${provider}.filter.enabled=true

Both includes and excludes can be specified, with excludes having a higher precedence in the evaluation.

j.s.p.${provider}.filter.include.name.groups=${group},${group},...
j.s.p.${provider}.filter.exclude.name.groups=${group},${group},...

When a probe with the name, com.acme.App.doWork, is created the following metering groups will be defined.

com
com.acme
com.acme.App
com.acme.App.doWork

Any one of the above metering groups can be used in a filter specification. Here is how to limit augmentation by a provider to all methods within the com.acme.App class except for doWork.

j.s.p.${provider}.filter.enabled=true
j.s.p.${provider}.filter.include.name.groups=com.acme.App
j.s.p.${provider}.filter.exclude.name.groups=com.acme.App.doWork

Guarding

The augmentation by a metering extension can be deferred until a probe is classified with one or more name labels.

j.s.p.${provider}.guard.name.labels=${label},${label},...

The augmentation by an extension provider is only activated when the name of a probe receives a classification by another metering extension such as hotspot. Here is how to defer the enhancement of a probe by an extension until the probe is labeled a hotspot.

j.s.p.${provider}.guard.name.labels=hotspot

For performance reasons the hotspot metering extension will eventually treat all hotspot labeled probes as unmanaged (!managed), after a period of time in which no change in its classification occurs.

j.s.p.${provider}.guard.name.labels=!managed

OSGi Issue

When profiling OSGi services add the agent to the bootclasspath as well:

-Xbootclasspath/a:/opt/satoris-${version}/agent/satoris-javaagent.jar

Depending on the OSGi implementation set the following property on the command line:

-Dorg.osgi.framework.bootdelegation=com.jinspired.*,org.jinspired.*

or alternatively

-Dorg.osgi.framework.bootdelegation=*

On popular OSGi platforms there is usually a conf/ directory with a config.properties file listing this system property. The property in the file may well override the system property set on the command line.

Probes Open API

Satoris is the default reference implementation of the Probes Open API – a standard for software activity metering. The JavaDoc can be found here.

Related Articles

Satoris — Metering is Profiling & More

Better Java Performance Profiling Tooling for the New Year

Anatomy of a Satoris Metered Runtime

An Open Modular Design for Performance Monitoring of Java

Goodbye, Tracing. Hello, Metering!

A new foundation for application performance monitoring

Integrating OpenTracing into Satoris

Extending Satoris with additional monitoring integrations

Metering is Monitoring, Memories, Mirroring & Management for the JVM

Satoris — The core runtime underlying Stenos, Simz and Sentris

Finding Java Hotspots with Satoris Hotspot

Getting the most out of the Satoris hotspot metering extension

The Realities of Java Performance Profiling

Professional Java Performance Profiling In Practice

Developing Custom Extensions for Satoris

Extending the Satoris metering engine via the Probes Open API

Self-Reflection of Java Performance Profile

Introspecting Instrumented Java using the Probes Open API

The Environment in the Probes Open API

How Satoris shares/records data and configure extension points.