Remote Network debugging and monitoring for Replicated Caches

Introduction

The ehcache-1.x-remote-debugger.jar can be used to debug replicated cache operations. When started with the same configuration as the cluster, it will join the cluster and then report cluster events for the cache of interest. By providing a window into the cluster it can help to identify the cause of cluster problems.

Packaging

From version 1.5 it is packaged in its own distribution tarball along with a maven module. It is provided as an executable JAR on the download page.

Limitations

This version of the debugger has been tested only with the default RMI based replication.

Usage

It is invoked as follows:

         java -jar ehcache-debugger-1.5.0.jar ehcache.xml sampleCache1 path_to_ehcache.xml [cacheToMonitor]

It takes one or two arguments:

  • the first argument, which is mandatory, is the Ehcache configuration file e.g. app/config/ehcache.xml. This file should be configured to allow Ehcache to joing the cluster. Using one of the existing ehcache.xml files from the other nodes normally is sufficient.
  • the second argument, which is optional, is the name of the cache e.g. distributedCache1

If only the first argument is passed, it will print our a list of caches with replication configured from the configuration file, which are then available for monitoring. If the second argument is also provided, the debugger will monitor cache operations received for the given cache. This is done by registering a CacheEventListener which prints out each operation.

NOTE: Adding Application Libraries to the Classpath
Use the Class-Path attribute inside a manifest file to add any additional libraries to the debugger's classpath. Be sure to leave a blank line at the end of the file. Following is an example of Class-Path attribute inside a manifest file (showing two separate JARs added to the classpath): Class-Path: lib/my.jar lib/myLoggerjar

Output

When monitoring a cache it prints a list of caches with replication configured, prints notifications as they happen, and periodically prints the cache name, size and total events received. See sample output below which is produced when the RemoteDebuggerTest is run.

   Caches with replication configured which are available for monitoring are:
  sampleCache19 sampleCache20 sampleCache26 sampleCache42 sampleCache33
  sampleCache51 sampleCache40 sampleCache32 sampleCache18 sampleCache25
  sampleCache9 sampleCache15 sampleCache56 sampleCache31 sampleCache7
  sampleCache12 sampleCache17 sampleCache45 sampleCache41 sampleCache30
  sampleCache13 sampleCache46 sampleCache4 sampleCache36 sampleCache29
  sampleCache50 sampleCache37 sampleCache49 sampleCache48 sampleCache38
  sampleCache6 sampleCache2 sampleCache55 sampleCache16 sampleCache27
  sampleCache11 sampleCache3 sampleCache54 sampleCache28 sampleCache10
  sampleCache8 sampleCache47 sampleCache5 sampleCache53 sampleCache39
  sampleCache23 sampleCache34 sampleCache22 sampleCache44 sampleCache52
  sampleCache24 sampleCache35 sampleCache21 sampleCache43 sampleCache1
  Monitoring cache: sampleCache1
  Cache: sampleCache1 Notifications received: 0 Elements in cache: 0
  Received put notification for element [ key = this is an id, value=this is
  a value, version=1, hitCount=0, CreationTime = 1210656023456,
  LastAccessTime = 0 ]
  Received update notification for element [ key = this is an id, value=this
  is a value, version=1210656025351, hitCount=0, CreationTime =
  1210656024458, LastAccessTime = 0 ]
  Cache: sampleCache1 Notifications received: 2 Elements in cache: 1
  Received remove notification for element this is an id
  Received removeAll notification.

Providing more Detailed Logging

If you see nothing happening, but cache operations should be going through, enable trace (LOG4J) or finest (JDK) level logging on net.sf.ehcache.distribution in the logging configuration being used by the debugger. A large volume of log messages will appear. The normal problem is that the CacheManager has not joined the cluster. Look for the list of cache peers.

Yes, but I still have a cluster problem

Check the FAQ where a lot of commonly reported errors and their solutions are provided. Beyond that, post to the forums or mailing list or contact Ehcache for support.