tquadrat's Foundation Library org.tquadrat.foundation.perflog 0.25.12 API

Performance Logging and Monitoring

This library provides a tool to permanently track the performance of an application or of subsystems inside that application. It is strictly not meant as a framework for benchmarking an application or algorithm.

It allows to observe how much time is used to perform a single operation within an application and whether this changes over time.

The application defines a Performance Section that wraps the operation to monitor. Each Performance Section has a unique name that is used for the statistics later. That name should be somehow meaningful.

The section registers the time when it was entered, and when it was left again, and the elapsed time will be made available to the monitoring system.

That monitoring system connects through JMX. This means it could either be an internal thread inside the same application, or another process on the same machine, or even a program running on another machine.

How to use it

The Performance Logging and Monitoring Manager

For the integration of the Performance Logging and Monitoring into an application, the first step is to create an instance of PerfLogManager; this is the frontend to the Performance Logging and Monitoring MBean that does the library's work behind the scenes.

Instances of PerfLogManager are thread-safe; it can be created as static or as an attribute:

…

/**
 *  The interface to the PerfLog MBean.
 */
private static final PerfLogManager PERFLOGMANAGER;

…

static
{
    //---* Initialise the Performance Logging *--------------------------------
    PERFLOGMANAGER = PerfLogUtils.createPerfLogManager();
}
…

Or it will be created for each method that should be monitored:

…

//---* Initialise the Performance Logging *------------------------------------
final var perfLogManager = PerfLogUtils.createPerfLogManager();

…

// Do something …

…

perfLogManager.close()

…

Because PerfLogManager implements AutoCloseable, it can also be used with try-with-resources:

…

//---* Initialise the Performance Logging *------------------------------------
try( final var perfLogManager = PerfLogUtils.createPerfLogManager() )
{
    // Do something …

    …
}
…

The Performance Sections

The next step is to define and to register the performance sections:

…

//---* Create the Performance Sections and add them *--------------------------
final var PS1 = PerfLogUtils.createPerformanceSectionName( "PS_Load" );
final var PS2 = PerfLogUtils.createPerformanceSectionName( "PS_Dump" );

perfLogManager.loadPerformanceSectionDefinition(
    new PerformanceSection( PS1, "Loading Data", null, null, SEND_REPORT_FOR_ABORT ),
    new PerformanceSection( PS2, "Dumping Data", new TimeValue( MILLISECOND, 500), null,
        SEND_REPORT_ONLY_FOR_EXCEEDED_THRESHOLD, SEND_REPORT_FOR_ABORT )
    }

…

The instances of PerformanceSection are stored globally by the PerfLogMBean. This means that each instance of PerfLogManager shares the same set of PerformanceSection definitions.

This allows to define and register them centrally, even if local manager instances are used:

…

/**
 *  The name for the performance section for loading data.
 */
public static final PerformanceSectionName PS1;

/**
 *  The name for the performance section for dumping data.
 */
public static final PerformanceSectionName PS2;

static
{
    //---* Initialise the Performance Logging *--------------------------------
    final var perfLogManager = PerfLogUtils.createPerfLogManager();

    //---* Create the Performance Sections and add them *----------------------
    PS1 = PerfLogUtils.createPerformanceSectionName( "PS_Load" );
    PS2 = PerfLogUtils.createPerformanceSectionName( "PS_Dump" );

    perfLogManager.loadPerformanceSectionDefinition(
        new PerformanceSection( PS1, "Loading Data", null, null, SEND_REPORT_FOR_ABORT ),
        new PerformanceSection( PS2, "Dumping Data", new TimeValue( MILLISECOND, 500), null,
            SEND_REPORT_ONLY_FOR_EXCEEDED_THRESHOLD, SEND_REPORT_FOR_ABORT )
        }
}

…

Threshold

The threshold time for a performance section is the execution duration for that section that is usually not exceeded. If that threshold limit is exceeded, a corresponding flag is set in the performance report.

When creating the performance section with the flag SEND_REPORT_ONLY_FOR_EXCEEDED_THRESHOLD, a performance report will be created only when the threshold is exceeded.

Timeout

If the execution of a performance section took longer than time configured for the timeout, the performance tracker will be aborted and a performance report is created. In this case, the exact execution time for the section is not tracked.

If both a threshold and a timeout value is set for the performance section, the timeout must but greater than the threshold.

Track the Performance

Before entering the code section that should be tracked, an instance of PerformanceTracker is requested from the PerfLogManager through a call to createPerformanceTracker() with the name of the performance section. If there is currently no performance section defined with that name, one will be created with default values (a dummy description, no threshold, no timeout, no flags – refer to PerformanceSection() for the details).

When the performance section is currently not active (PerformanceSection.isIgnored() returns true), the call to createPerformanceTracker() returns empty.

When entering the code section, the tracker needs to be started, and at the end, its should be stopped or, in case of an error, aborted.

That may look like this:

final var perfLogManager = PerfLogUtils.createPerfLogManager();
…

//---* Load Data *-------------------------------------------------------------
final var tracker = perfLogManager.createPerformanceTracker( PS1 );
try
{
    tracker.ifPresent( t ->
    {
        t.setContext( "Source", … );
        t.start();
    });

    // Do something here!!
    …

    tracker.ifPresent( PerformanceTracker::stop() );
}
catch( final AnException e )
{
    tracker.ifPresent( t -> t.abort( "An exception was caught", e ) );
}

The utility class PerfLogUtils has the methods hold() and holdAndStart() that allows to use try-with-resources:

final var perfLogManager = PerfLogUtils.createPerfLogManager();
…

//---* Load Data *-------------------------------------------------------------
try( final var tracker = PerfLogUtils.hold( perfLogManager.createPerformanceTracker( PS1 ) ) )
{
    tracker.setContext( "Source", … );

    try
    {
        tracker.start();
        // Do something here!!
        …
    }
    catch( final AnException e )
    {
        tracker.abort( "An exception was caught", e );
    }
}

Or without the option to abort the performance tracker and with an internal, volatile Performance Logging Manager:

//---* Load Data *-------------------------------------------------------------
try( final var tracker = PerfLogUtils.holdAndStart( PS1 ) )
{
    tracker.setContext( "Source", … );

    // Do something here!!
    …
}

The Context

If the execution time for a performance section is (probably) dependent on some data, this can be documented through the context that is stored with the tracker instance.

PerformanceTracker.addContext() takes a category key and the related value; this allows to provide some structured data:

//---* Load Data *-------------------------------------------------------------
try( final var tracker = PerfLogUtils.hold( perfLogManager.createPerformanceTracker( PS1 ) ) )
{
    final var source = Path.of( fileName );
    final var lastModified = ZonedDateTime.ofInstant( Instant.ofEpochMilli( Files.getLastModifiedTime( source ).toMillis() ), UTC );
    final var size = new DataSizeValue( BYTE, Files.size( source ) );
    final var lineCounter = new AtomicInteger( 0 );

    tracker.setContext( "Source", source.toString );
    tracker.setContext( "Source Date", lastModified.format( DateTimeFormatter.ISO_ZONED_DATE_TIME );
    tracker.setContext( "Source Size", "%0.1s".formatted( size.convert( KIBIBYTE ) );

    try
    {
        tracker.start();
        Files.lines( source )
            .peek( _ -> lineCounter.incrementAndGet() )
            .forEach( line -> /* Do something here!! */ );
        tracker.setContext( "Source Lines", lineCounter.toString() );

        …
    }
    catch( final IOException e )
    {
        tracker.abort( "An exception was caught", e );
        throw e;
    }
}
catch( final IOException e )
{
    // Handle the exception …
}

When reusing the tracker instance, it is possible to keep the current context and only overwrite some of the entries; refer to PerformanceTracker#reset().

Receiving the Performance Reports

Once a performance tracker terminates, a performance report is created by the Performance Logging and Monitoring MBean, then it will be issued by it as a Notification.

The report data is stored in JSON format in the message part of the notification.

Such a report may look like this:

{
  "PerformanceSection":
  {
    "Name":"PS_Load",
    "Description":"Loading Data",
    "ThresholdOnlyReport":false
  },
  "StartTime":"2026-05-17T09:43:46.723338398Z",
  "ElapsedTime":
  {
    "Unit":"ms",
    "Value":29001.241731
  },
  "ExceededThreshold":false,
  "IsTimedOut":false,
  "IsAborted":false,
  "Context":
  {
    "Source":"…",
    "Source Date":"…",
    "Source Size":"…",
    "Source Lines":"…"
  }
}

Internal Client

For a client that runs within the same JVM as the application itself, the class PerfLogClientSupport can be used like this:

/**
 *  Receive the Performance Logging and Monitoring Notifications and
 *  process them.
 */
public final void run()
{
    final var mbeanServer = obtainMBeanServer();
    try( final var clientSupport = new PerfLogClientSupport() )
    {
        clientSupport.connect( mbeanServer, true );
        var proceed = true;
        while( proceed )
        {
            try
            {
                final var message = clientSupport.awaitMessage();
                // Process the message!!
            }
            catch( final InterruptedException _ )
            {
                proceed = false;
            }
        }
    }
    catch( final InstanceNotFoundException e )
    {
        throw new UnexpectedExceptionError( "Should not happen as we set force = 'true' when connecting", e );
    }
}   //  run()

Remote Client

If a client running inside another JVM should be used, either on the same or another machine, if is necessary to expose the MBeanServer first:

import static org.tquadrat.foundation.mgmt.JMXUtils.enableRemoteAccess;
import java.rmi.RemoteException;
import java.io.IOException;
…

try
{
    final var mbeanServer = obtainMBeanServer();
    final var url = enableRemoteAccess( mbeanServer, 9999, Map.of() );
}
catch( final IOException | RemoteException e )
{
    err.println( "Cannot expose MBeanServer" );
    e.printStackTrace( err );
}

The library org.tquadrat.foundation.perflog.remote provides a helper class for the implementation of a remote client.

A simple implementation could look like this:

…
public final class RemoteClient
{
        /*---------*\
    ====** Methods **==========================================================
        \*---------*/
    /**
     *  The implementation for
     *  {@link NotificationListener}.
     *
     *  @param  notification    The notification.
     *  @param  handback    The handback.
     */
    private static final void listener( final Notification notification, final Object handback )
    {
        out.printf( """
            Type:    %1$s
            Message: %3$s
            SeqNo:   %2$d
            -------------------------------------------------------------------
            """, notification.getType(), notification.getSequenceNumber(), notification.getMessage() );
    }   //  listener()

    /**
     *  The program entry point.
     *
     *  @param  args    The command line arguments.
     */
    public static final void main( final String... args )
    {
        //---* Initialise the error handling *---------------------------------
        currentThread().setUncaughtExceptionHandler( RemoteClient::uncaughtExceptionHandler );

        while( true )
        {
            try( final var remote = PerfLogRemote.connect( 9999, RemoteClient::listener ) )
            {
                out.println( remote.getMBeanInfo() );
                for( final var name : remote.getPerformanceSections() )
                {
                    out.println( remote.getPerformanceSection( name ) );
                }
                out.println( "=".repeat( 67 ) );
                while( true );
            }
            catch(  final IOException | InstanceNotFoundException | ReflectionException | IntrospectionException | AttributeNotFoundException | MBeanException e )
            {
                e.printStackTrace( err );
            }
        }
    }   //  main()

    /**
     *  An implementation of
     *  {@link Thread.UncaughtExceptionHandler}.
     *
     *  @param  t   The aborted thread.
     *  @param  e   The
     *      {@link Throwable}
     *      that caused the abort.
     */
    private static final void uncaughtExceptionHandler( final Thread t, final Throwable e )
    {
        err.printf( "Thread %s aborted due to an exception%n", t.getName() );
        e.printStackTrace( err );
    }   //  uncaughtExceptionHandler()
}
//  class Client
…

Modules

Module	Description
org.tquadrat.foundation.library.org.tquadrat.foundation.perflog	The module for the performance logging and monitoring classes of the Foundation Library.