Terracotta Management Console

The Terracotta Management Console (TMC) is a web-based administration and monitoring application for standalone Ehcache.

Setting Up User Accounts

The account setup page appears when you first log into the Terracotta Management Console (TMC) using the temporary initial login credentials.

The account setup page is where you initialize the two role-based accounts that can access the TMC:

• Administrator – This account has read-write control over all aspects of the TMC, including accounts and connections.
• Operator – This read-only account can view statistics and other information about configured connections. This account cannot add or edit accounts or connections.

After you enter a username and password for each account, click Setup. You will be logged out, and the initial login credentials can no longer be used. Users can now log in using the credentials you have set up.

Once a user logs in, there is no default timeout for inactivity. To set a default timeout for inactivity, uncomment the following block in web.xml and set the timeout value (in minutes) using the <param-value> element:

  <context-param> 
    <description>
      After this amount of time has passed without user activity, the user will be
      automatically logged out.
    </description>
    <param-name>idleTimeoutMinutes</param-name> 
    <param-value>30</param-value> 
  </context-param>

Navigating the TMC User Interface

Managing Connections

When you initially log on to the TMC, only the default connection group and default connection exist. If a node that can be monitored is running on localhost at the port specified by the default connection, then the default connection will appear as an active connection. If not, then the default connection appears as an unavailable (inactive) connection.

You can create and edit managed connections and connection groups using the Manage Connections dialog. To open the Manage Connections dialog, click Manage Connections on the tool bar. Click Close to dismiss the Managed Connections dialog.

Working With Connection Groups

Managed connections can be assigned to custom connection groups to simplify management tasks. Managed connections not explicitly assigned to a group are in the default group.

Connection groups appear as top-level items in the left-hand navigation menu.

Adding a Connection Group

To add a new managed connection, follow these steps:

1. Click Managed Connections on the tool bar to open the Managed Connections dialog.
2. Click the + (plus) above the list of connection groups.

The New Connection Group panel appears.

3. Enter a name for the new connection group.
4. Click Apply to save the new group or Cancel to discard the new group.

Saved new groups appear in the connection-group list, connection details, and the TMC navigation panel.

Editing or Deleting a Connection Group

To edit an existing connection group, choose the connection group in the Connection Groups list, then click Edit in the Connection Group Details panel. A dialog allows you to change the name of the connection group, and to confirm or cancel the change.

To delete an existing connection group, choose the connection group in the Connection Groups list, then click Delete in the Connection Group Details panel. A dialog allows you to confirm or cancel the delete operation.

Working With Managed Connections

Managed connections are connections that you monitor and administer using the TMC.

Adding a Managed Connection

To add a new managed connection, follow these steps:

1. Click Managed Connections on the tool bar to open the Managed Connections dialog.
2. Click the + (plus) above the list of connections.

The connection details panel appears.

3. Choose a group for the new connection from the Groups menu.

A managed connection can be assigned to more than one connection group.

4. Enter a name to identify the connection.
5. Enter the location of the node you want to monitor. Note that the location is relative to the machine running the Terracotta Management Server (TMS) - so "localhost" would be the machine the TMS is running on, which is not necessarily the machine your browser is running on.

The location is a URI in the following form:

<scheme>:<host>:<port>

A typical URI will appear similar to:

http://my-ehcache-host:9888

6. Enter a connection timeout or accept the default value.

The connection timeout limits the time for successfully establishing a connection to the node. This ensures that the TMC does not hang waiting for a connection in the case where the node is unreachable.

7. Enter a read timeout or accept the default value.

The read timeout limits the time the TMC waits for data from a connected node. This ensures that the TMC does not hang waiting for a connection in the case where the node is unresponsive.

8. Click Apply to save the new connection or Cancel to discard the new connection.

Saved connections appear in the connections menu. If the connection cannot be established, a warning appears.

Editing and Deleting Managed Connections

Managed connections that appear in the connections list can be edited or deleted.

To edit an existing managed connection, follow these steps:

1. Click Managed Connections on the tool bar to open the Managed Connections dialog.
2. Select the managed connection to edit from the connections list.

The connection details panel appears.

3. Click Edit on the connection details panel.

A managed connection can be assigned to more than one connection group.

4. Click Apply to save the new connection or Cancel to discard the new connection.

To delete an existing connection, select the connection in the connections list, then click Delete on the connection details panel. A dialog allows you to confirm or cancel the delete operation.

Monitoring Connection Groups

When a connection group is selected in the navigation menu, the group's connections are shown. Active connections are listed under the Active Connections tab. Inactive (unreachable) connections are listed under the Unavailable Connections tab.

Connections are grouped by category. Ehcache connections are listed in the "EHCACHE" section.

Monitoring Ehcache Connection Groups

Ehcache connection groups appear nested under top-level connection groups in the navigation menu. To view existing Ehcache connection groups under a particular connection group, expand that connection group. The Ehcache connection group is the node labeled "Ehcache".

Select an Ehcache connection group in the navigation menu to display an overview panel with a table of Ehcache statistics for all Ehcache connections. The statistics table has the following columns:

• Connection – The name of the Ehcache connection.

Names can be edited in Manage Connections.

• Elements – The total number of elements for all caches included in the named connection.
• Hit Ratio – The average hits/misses ratio for all caches included in the named connection.
• OnHeap Usage – The total amount (in megabytes) of heap memory used by all caches included in the named connection.
• OffHeap Usage – The total amount (in megabytes) of off-heap memory used by all caches included in the named connection.

Off-heap memory is RAM not used by the heap but available to the caches through BigMemory.

Only active connections appear under the connection category.

Managing Ehcache

When an Ehcache connection is selected in the navigation menu, connection management panels are activated.

To monitor a specific Ehcache connection, expand its Ehcache connection group in the navigation menu, then select the target Ehcache connection.

Ehcache Overview Panel

The Ehcache connection Overview tab displays configuration and health metrics for CacheManagers and caches. To toggle between the two, click Health Metrics or Topology.

Topology

The Ehcache connection Topology panel allows you to view the caches available under active CacheManagers. To view the caches under a specific CacheManager, expand that CacheManager.

To view a CacheManager's configuration, select that CacheManager by clicking its name. Then click the config link next to the CacheManger's name to open a window containing its configuration.

To view a cache's configuration, select that cache by clicking its name. Then click the config link next to the cache's name to open a window containing its configuration.

Health Metrics

The Health Metrics panel displays certain cache statistics to help you track performance and resource usage across all CacheManagers. Statistics are displayed in a table with the following columns:

• CacheManager – The name of the CacheManager.
• Status – The CacheManager's status (ALIVE, SHUTDOWN, UNINITIALISED). An UNINITIALISED status may change to ALIVE once a CacheManager has completed the initialization process.
• Hit Rate (hits/s) – The number of hits per second on all of the CacheManager's caches.
• Element Count – The total number of elements in all of the CacheManager's caches.
• OffHeap Usage – The total percentage of off-heap memory being used by all of the CacheManager's caches.

To view the hit rate, element count, and off-heap usage for each of a CacheManager's caches, expand that CacheManager.

Ehcache Monitoring Panel

Use the Monitoring tab to display cache statistics for tracking the performance of Ehcache and discovering issues. Statistics can be viewed in chart or table format. To toggle between the two, click Charts or Statistics.

Use the pull-down menus to display statistics for any connected CacheManager. For charts, you can select to view statistics for a specific cache or for all of the selected CacheManager's caches.

Charts

Cache statistics charts graph real-time values for a number of cache metrics.

System time is plotted along each chart's X axis, while the statistical values are plotted along the Y axis. To view the value of any single point on graph, float the mouse pointer over that point. This also displays the units used for the statistic being graphed.

To choose the type of statistic graphed by a particular chart, click the chart to open a list of available statistics. Choose a statistic, then click OK to accept the change. The chart immediately begins to graph the chosen statistic.

Statistics

The cache-statistics table displays real-time values for a number of cache metrics.

To choose the types of statistics displayed in the table, click Configure Columns to open a list of available statistics. Choose statistics, then click OK to accept the change. The chart immediately begins to graph the chosen statistic.

Ehcache Cache Management Panel

The Management panel displays a table listing the active CacheManagers for the selected Ehcache connection. The table's first column lists the name of the CacheManager. The remaining columns display the following CacheManager information:

• Enabled – The total number of enabled caches over the total number of configured caches. Click this cell to activate the Disable All control which can disable the operations of all of the listed caches at once.
• Statistics – The total number of caches with statistics enabled over the total number of configured caches. Click this cell to activate the Disable All control which can disable statistics gathering for all of the listed caches at once.
• Element Count – The total number of elements in all of the CacheManager's caches. Click this cell to activate the Clear Caches control which can wipe the data of all of the listed caches at once.

Click the arrowhead next to a CacheManager name in the table to expand a nested table listing all of that CacheManager's caches. The table's first column lists the name of each cache. The remaining columns display the following attributes and metrics:

• Enabled – Indicates whether the cache is enabled ("true") or disabled ("false"). Click this cell to activate the Disable control which can disable the operations of the cache.
• Statistics – Indicates whether statistics gathering for the cache is enabled ("true") or disabled ("false"). Click this cell to activate the Disable control which can disable statistics gathering for the cache.
• Element Count – The total number of elements in the cache. Click this cell to activate the Clear Cache control which can wipe the data of the cache.

Ehcache Diagnostics Panel

The Diagnostics panel provides information on the usage of the heap, off-heap, and disk tiers by the caches of the selected CacheManager. To view tier usage by any active CacheManager, select that CacheManager from the CacheManager drop-down menu.

Usage by Tier

The Relative Cache Sizes by Tier table displays usage of the tier selected from the Tier drop-down menu. The table has the following columns:

• Cache – The name of the cache.
• Size (MB) – The size of the cache's data in megabytes.
• % of Used – Percent of the total storage allotted to the cache that is currently used for cache data.
• Entries – The total number of cache entries.
• Mean Entry Size (bytes) – An estimate of the average size of each cache entry.

Click a row in the table to set the cache-related tier graphs to display values for the named cache.

Usage Graphs

The panel shows the following bar graphs:

• CacheManager Usage by Tier – Overall usage of each tier.
• Cache Usage by Tier – Usage of each tier by the selected cache. Choose the cache from the Selected Cache drop-down menu.
• Cache Miss Rate by Tier – The rate of cache misses at each tier. Usage of each tier by the selected cache. Choose the cache from the Selected Cache drop-down menu.

Float the mouse pointer over a bar to display an exact usage value. Click a tier's bar to display values for that tier in the Relative Cache Sizes by Tier table.

The Selected Cache Menu

The Selected Cache drop-down menu determines which cache is shown in the cache-related tier graphs and highlighted in the Relative Cache Sizes by Tier. The menu also indicates if the cache uses size-based (ARC) or entry-based sizing.