Features

Germain can monitor any Java application. The main features of the Germain Java Application monitoring are:

  • CPU and memory usage

  • HTTP requests (inbound and outbound)

  • JMS messages (inbound and outbound)

  • SQL transactions

  • Calls to any Class Method (custom list at application startup)

  • Sampler to collect CPU profiling information

  • JMX access for inspecting agent statistics or configuration remotely (optional)

Requirements

  • JRE 8 (Java version 1.8)

Installation

There are three steps to installation:

  1. Placing the two agent JAR files in a location accessible to all applications that will be monitored.

  2. Creating a configuration file for each of the applications being monitored.

  3. Starting those applications with an additional -javaagent argument to the JVM.

Files provided by germain

  • apm-agent.jar

  • apm-agent-runtime.jar

  • agent.properties

  • germain.java.security

Configuration files

The agent.properties file is a generic template that can be copied and filled in for each application. Suggestion: name each copy agent-[APPLICATION_NAME].properties so they can all reside in the same folder. See the section on configuration for the meaning of each property.

JVM Argument

Any scripts used to start the existing Java applications need to be modified to pass an additional -javaagent argument to the JVM.

-javaagent:[PATH_TO_AGENT_JAR_FILE]=[PATH_TO_PROPERTIES_FILE]

IBM JVM only JVM Argument:

If you are using the IBM JVM you will need to add the following to any scripts used to start the existing Java applications to include the germain.java.security file.

-Djava.security.properties=/[PATH_TO_SECURITY_FILE]/germain.java.security

Configuration

Each property described below is necessary to include as a line in a properties file if the desired setting is different than the default value. A minimal properties file includes the agent.url of the APM server, and *.enabled=true for the desired features. Logging functionality is there to assist advanced debugging and is not necessary to configure under normal circumstances.

Note: The agent properties file uses the Properties File Format, and as such, backslash (\) is an escape character, and lines starting with a pound sign (#) or exclamation mark (!) are ignored and can be used to comment out the line.

agent.*

agent.application = My application's name
agent.numThreads  = 2
agent.runtimeJar  = C:\\germain\\agent\\apm-agent-runtime.jar
agent.url         = http://localhost:8080/ingestion/agent
TEXT

Property name

Description

Default value

agent.application

The name of the application being monitored.

The auto-detected name of the application.

agent.numThreads

Number of threads used by the germain agent.

2

agent.runtimeJar

Path to apm-agent-runtime.jar.

The same path as the apm-agent.jar appended with /apm-agent-runtime.jar

agent.url

The URL of the APM server.

http://localhost:8080/ingestion/agent

agent.feature.*

agent.feature.servlet.enabled = true
agent.feature.outboundHttp.enabled = true
agent.feature.jdbc.enabled = true
agent.feature.jms.enabled = true
agent.feature.processMetrics.enabled = true
agent.feature.processMetrics.interval = 60
agent.feature.cpuProfiling.enabled = true
agent.feature.method.enabled = true
agent.feature.method.0.path = com.packagename.ClassName.methodName
agent.feature.method.0.type = eventName0
agent.feature.method.1.path = com.packagename.ClassName.methodName
agent.feature.method.1.type = eventName1
TEXT

Property name

Description

Default value

agent.feature.servlet.enabled

HTTP Servlet monitoring

false

agent.feature.outboundHttp.enabled

Outbound HTTP request monitoring

false

agent.feature.jdbc.enabled

JDBC SQL database monitoring

false

agent.feature.jms.enabled

JMS monitoring

false

agent.feature.processMetrics.enabled

Java process metrics

false

agent.feature.processMetrics.interval

Time between each sample (seconds)

60

agent.feature.cpuProfiling.enabled

CPU profiling

false

agent.feature.cpuProfiling.duration

Sampler duration (seconds)

60

agent.feature.method.enabled

Custom method monitoring

false

agent.feature.method.0.path

The fully qualified method name of the first method to be monitored.

agent.feature.method.0.type

A keyword to label this kind of event. Required for each corresponding path.

agent.feature.method.1.path

The fully qualified method name of a second method to be monitored.

agent.feature.method.1.type

A keyword to label this kind of event. Does not necessarily have to be distinct from other type values if it captures the same kind of event.

agent.feature.method...

Any number of methods can be monitored as long as they are numbered sequentially starting with 0.

agent.log.*

agent.log.type = FILE
agent.log.level = DEBUG
agent.log.name = agent
agent.log.path = C:\\germain\\logs
TEXT

Property name

Description

Default value

agent.log.type

NULL, FILE, CONSOLE

agent.log.level

ERROR, WARN, INFO, DEBUG, TRACE, NONE

NONE

agent.log.name

The prefix for log file names.

agent.log.path

Directory path for file logger.

agent.packages.*

agent.packages.skiplist = java,javax,sun,com.germainsoftware.agent,com.mysql,com.zaxxer.hikari,oracle,org.apache,org.glassfish,org.springframework
agent.packages.blacklist = com.germainsoftware.agent
TEXT

Property name

Description

Default value

agent.packages.skiplist

Comma-delimited list of Class packages that should be ignored when the agent is determining the application-level caller.

java,

javax,

sun,

com.germainsoftware.agent,

com.mysql,

com.zaxxer.hikari,

oracle,

org.apache,

org.glassfish,

org.springframework

agent.packages.blacklist

Comma-delimited list of Class packages whose Classes should never generate data as application-level callers.

com.germainsoftware.agent

agent.queue.*

agent.queue.maxSize = 10000
agent.queue.batchSize = 500
agent.queue.threads = 2
TEXT

Property name

Description

Default value

agent.queue.maxSize

The number of data points that will be held before dropping data from the APM Datamart queue.

10000

agent.queue.batchSize

The number of data points to send per batch.

500

agent.queue.threads

Threads used for submitting batches.

1

Inspecting the agent via JMX

The Germain Java agent registers multiple MBeans via JMX to expose additional statistics at run-time. Any JMX client, such as VisualVM with the MBeans plugin, can be used to connect to the Java process and browse the exported objects.

Caveats of CPU sampling

  • The agent runs inside the JVM; that means that program errors can affect the monitored application - this is true for any profiler

  • The agent runs inside the JVM, thus it is subject to Java timer accuracy and garbage collection

  • The agent cannot distinguish between overloaded methods because they are stored ambiguously in the stack trace.

  • The agent only counts threads which are in RUNNABLE state

  • Time spent in filtered methods will be attributed to the last unfiltered caller method