Download the latest version of Satoris, an advance adaptive metering engine, to profile and monitor Java applications amongst other things. There is so much to tell about the large number of amazing extensions that are distributed with Satoris, which make it an exemplary measurement framework for Stenos, Simz, and Sentris but that will have to wait for another day when a planned software metering book is published later in the year. Let’s now get the free software download started!

satoris- satoris-

Before skipping along to our intentionally short getting started guide, consider joining our Slack channel to learn more. Need an invite? Send an email request.

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.


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


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


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:


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

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

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

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

Exclusions have higher precedence over inclusions.

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

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

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

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

# include only those classes containing ".jdbc."
# include all classes except those containing ".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
# exclude the acme.HelloWorld class ignoring inner classes or classes nested in a same named package

A condition starting with [ represents a class bytecode contains match

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

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:


The agent will not instrument classes within the following packages:


The agent will not instrument classes containing the following strings:


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.


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:


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


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


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


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


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.


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


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.


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.


OSGi Issue

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


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


or alternatively


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.