Loupe Agent for Java

The Loupe Agent provides a generic facility for capturing log messages, exceptions, and metrics from Java applications. This product was written in Java 1.8, and no warranty is made for the stability or maximum efficiency of the product in earlier versions of Java.

What's In This Repository

This repository contains a maven reactor encompassing the supported inventory of Loupe, including:

• Loupe model: The project containing our common entities.
• Loupe core: The project containing the generic facility for our functionality. This is what powers our appenders and what one would use to extend Loupe.
• Loupe api: A layer of convenience functionality for those who wish to use Loupe directly.
• Loupe log4j support: Our appender for log4j support.
• Loupe log4j2 support: Our appender for log4j2 support.
• Loupe logback support: Our appender for logback support.

How do I add Loupe to my Application?

Download Loupe

Central Repository

Loupe is readily available at The Central Repository!

Supported build automation tools include:

• Maven
• Gradle
• SBT
• Ivy
• Grape
• Leiningen
• Buildr

Manual / Local Repository

To add Loupe to your application manually, first use GIT to clone our repository:

https://github.com/GibraltarSoftware/loupe-java.git

or

[email protected]:GibraltarSoftware/loupe-java.git

While Loupe can be retrieved from Central by a variety of build automation tools, it is itself built using Maven. Navigate to the root of the parent project folder, you will see a POM file. Execute:

mvn clean install

This will deploy Loupe to your local Maven repository.

Install Loupe in your application

Install Loupe using Maven

Add the following dependency (logback support for example, see full inventory to select an appropriate module) to your pom.xml:

	<dependency>
		<groupId>com.onloupe</groupId>
		<artifactId>loupe-logback-support</artifactId>
		<version><...desired version...></version>
	</dependency>

Execute the necessary commands to build your application in Maven.

Install Loupe manually

If you do not wish to use Maven in your application, Loupe can be built and deployed manually.

Build Loupe

Navigate to the root of the parent project folder, you will see a POM file. Execute:

mvn clean install

This will generate the necessary artifacts to install and run Loupe.

These artifacts can be found relative to the parent root:

<product>/target/<product>-<version>.jar

Note: Any manual installation must include the following jars:

• model
• core

Ergo, installing loupe-log4j2-support would include deployment of jars:

• model
• core
• loupe-log4j2-support

...plus the collateral dependencies detailed in the parent POM file.

Install Loupe

Once you've selected your jar files, add them to the classpath of the container or java runtime as your setup requires. They will then be available to your application.

Additional dependency injection platforms (gradle, etc) are under consideration for future inclusion.

Configuring Loupe

Loupe can be configured in a variety of ways

AgentConfiguration object injection

Loupe can be configured directly using its configuration object, for a robust example:

    AgentConfiguration configuration = AgentConfiguration.builder()
				.networkViewer(NetworkViewerConfiguration.builder()
						.allowLocalClients(false)
						.allowRemoteClients(true)
						.maxQueueLength(10)
						.enabled(false).build())
				.server(ServerConfiguration.builder()
						.enabled(false)
						.autoSendSessions(true)
						.autoSendOnError(false)
						.sendAllApplications(true)
						.purgeSentSessions(true)
						.customerName("GibraltarSoftware")
						.useGibraltarService(true)
						.useSsl(true)
						.server("onloupe.com")
						.port(81)
						.applicationBaseDirectory("C:\\base\\directory")
						.repository("ourRepo").build())
				.listener(ListenerConfiguration.builder()
						.autoTraceRegistration(false)
						.enableConsole(false)
						.enableNetworkEvents(false)
						.endSessionOnTraceClose(false).build())
				.sessionFile(SessionFileConfiguration.builder()
						.enabled(false)
						.autoFlushInterval(42)
						.indexUpdateInterval(42)
						.maxFileSize(42)
						.maxFileDuration(42)
						.enableFilePruning(false)
						.maxLocalDiskUsage(42)
						.maxLocalFileAge(42)
						.forceSynchronous(true)
						.maxQueueLength(42)
						.minimumFreeDisk(42)
						.folder("C:\\Temp").build())
				.publisher(PublisherConfiguration.builder()
						.productName("Sample")
						.applicationDescription("Sample App")
						.applicationName("Loupe")
						.applicationType(ApplicationType.ASP_NET)
						.applicationVersion(new Version(42, 0, 0))
						.environmentName("Development")
						.promotionLevelName("QA")
						.forceSynchronous(true)
						.maxQueueLength(10)
						.enableAnonymousMode(true)
						.enableDebugMode(true).build())
				.packager(PackagerConfiguration.builder()
						.hotKey("Ctrl-Alt-F5")
						.allowFile(false)
						.allowRemovableMedia(false)
						.allowEmail(false)
						.allowServer(false)
						.fromEmailAddress("[email protected]")
						.destinationEmailAddress("[email protected]")
						.productName("Sample")
						.applicationName("Loupe").build())
				.build();

The configuration object can then be injected in an explicit call to start Loupe:

    Log.start(configuration);

or, if using loupe-api:

    Loupe.start(configuration);

Properties files

Loupe can also be configured using properties files. The properties file need only be placed on the classpath, and Loupe will detect and utilize it. Loupe supports the PROPERTIES or XML file format.

Properties file

Name: loupe.properties

Publisher.ProductName=TestApps
Publisher.ApplicationName=SpringTests
Server.AutoSendSessions=true
Server.Server=hub.gibraltarsoftware.com
Server.Repository=esymmetrix
Server.UseSsl=true
NetworkViewer.AllowRemoteClients=true

XML properties file

Nane: loupe.xml

<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
	<entry key="Publisher.ProductName">TestApps</entry>
	<entry key="Publisher.ApplicationName">SpringTests</entry>
	<entry key="Server.AutoSendSessions">true</entry>
	<entry key="Server.Server">hub.gibraltarsoftware.com</entry>
	<entry key="Server.Repository">esymmetrix</entry>
	<entry key="Server.UseSsl">true</entry>
	<entry key="NetworkViewer.AllowRemoteClients">true</entry>
</properties>

Configuring Loupe appenders for logging platforms

Logback

Maven configuration

		<dependency>
			<groupId>com.onloupe</groupId>
			<artifactId>loupe-logback-support</artifactId>
			<version>... desired version ...</version>
		</dependency>

Logback configuration

Add the following appender to logback.xml, scoped in accordance with your choosing.

<appender name="loupe" class="com.onloupe.appenders.logback.LoupeLogbackAppender"/>

Log4j2

Maven configuration

		<dependency>
			<groupId>com.onloupe</groupId>
			<artifactId>loupe-log4j2-support</artifactId>
			<version>... desired version ...</version>
		</dependency>

Log4j2 configuration

First, the configuration route must include the package path to the Loupe appender.

<Configuration packages="com.onloupe.appenders.log4j">

Next, add the appender to the appenders inventory:

<LoupeLog4jAppender name="Loupe" />

Finally, add our appender to any scope of your choosing.

Log4j

Maven configuration

		<dependency>
			<groupId>com.onloupe</groupId>
			<artifactId>loupe-log4j-support</artifactId>
			<version>... desired version ...</version>
		</dependency>

Log4j configuration

Add the appender to the appenders inventory:

<appender name="LoupeLog4jAppender" class="com.onloupe.appenders.log4j.LoupeLog4jAppender"/>

Finally, add our appender to any scope of your choosing.

Creating Custom Metrics in Loupe

Loupe supports two types of metrics:

Event Metrics

Loupe uses Event Metrics to capture data about singular events at a specific point in time.

The example below pertains to metrics concerning a hypothetical database cache:

@EventMetricClass(namespace = "Samples", categoryName = "Database.Engine", 
	counterName = "Cache - Declarative", caption = "Simple Cache", 
	description = "Performance metrics for the database engine.")
public class CacheEventMetric
{
	private String instanceName;
	private int pages;
	private int size;

	public CacheEventMetric(String instanceName, int pages, int size) {
		super();
		this.instanceName = instanceName;
		this.pages = pages;
		this.size = size;
	}
	
	// An optional member to be automatically queried for the instance name 
	// to use for this event metric on this data object instance.
	@EventMetricInstanceName
	public final String getInstanceName() {
		return instanceName;
	}
	
	// An event metric value representing the average of pages in the cache over time.
	@EventMetricValue(name = "pages", summaryFunction = SummaryFunction.AVERAGE, 
		caption = "Pages", description = "Total number of pages in cache.")
	public final int getPages() {
		return pages;
	}
	
	// An event metric value representing the average size of the cache over time.
	@EventMetricValue(name = "size", summaryFunction = SummaryFunction.AVERAGE, 
		unitCaption = "Bytes", caption = "Cache Size", 
		description = "Total number of bytes used by pages in cache.")
	public final int getSize() {
		return size;
	}
}

To utilize the above event metric class, the following code is executed:

// register the class and bind the fields.
EventMetric.register(CacheEventMetric.class);

// capture a metric
CacheEventMetric oneMetric = new CacheEventMetric("one", 388, 2048);
EventMetric.write(defaultInstance);

// create another metric
CacheEventMetric metric = new CacheEventMetric("two", 122, 1024);
// if an attribute is not found, we fall back to the instance name "one"
EventMetric.write(metric, "one");

Sampled Metrics

Loupe uses Sampled Metrics to capture data points at a defined interval over the course of time.

@SampledMetricClass(namespace = "Samples", categoryName = "Database.Engine")
public class CacheSampledMetric
{
	private String instanceName;
	private int pages;
	private int size;

	public CacheSampledMetric(String instanceName, int pages, int size) {
		super();
		this.instanceName = instanceName;
		this.pages = pages;
		this.size = size;
	}
	
	// An optional member to be automatically queried for the instance name 
	// to use for this sampled metric on this data object instance.
	@SampledMetricInstanceName
	public final String getInstanceName() {
		return instanceName;
	}
	
	// A sampled metric value representing the number of pages at the point in time of
	// execution.
	@SampledMetricValue(counterName = "pages", samplingType = SamplingType.RAW_COUNT, 
		caption = "Pages in Cache", description = "Total number of pages in cache")
	public final int getPages() {
		return pages;
	}
	
	// A sampled metric value representing the average size of the cache over time.
	@SampledMetricValue(counterName = "size", samplingType = SamplingType.RAW_COUNT, 
		unitCaption = "Bytes", caption = "Cache Size", 
		description = "Total number of bytes used by pages in cache")
	public final int getSize() {
		return size;
	}
}

To utilize the above event metric class, the following code is executed:

// register our metric type
SampledMetric.register(CacheSampledMetric.class);

// write a metric with the ascribed values
SampledMetric.write(new CacheSampledMetric("cacheMetric", 122, 1024));

Where are my local log files?

You may define which directory Loupe will use to store log files (extension .glf) by defining the following property:

SessionFile.Folder=<fully qualified path>

If this value is undefined, Loupe will attempt to place log files in the most sensible location available based on the state of the host operating system.

Windows

First, Loupe will attempt to use the common application data folder:

C:\ProgramData\Gibraltar\Local Logs

If the common application data folder is unavailable, the local data folder will be attempted:

C:\Users\<user name>\AppData\Gibraltar\Local Logs

Failing both of these, the Java tmp io directory will be used.

Linux

First, Loupe will attempt to use the common logging area:

/var/log/Gibraltar/Local Logs

By default, this folder is generally not available for write operations by users outside of it's group. This will need to be handled accordingly when provisioning the user running the Loupe agent or appenders.

Otherwise, Loupe will attempt to use a hidden folder in the user home directory:

/home/<user name>/.logs/Gibraltar/Local Logs

Failing both of these, the Java tmp io directory will be used.

How do I view my local log files??

Download the latest version of Loupe desktop.

This software runs on Windows only, but can still open GLF files generated by linux hosted applications.

License Information

Loupe is released under version 2.0 of the Apache License.