Terracotta logo

Terracotta Management Console

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

To confirm the version of the TMC you are running, and for other information about the TMC, choose About from the toolbar.

Setting Up User Accounts

When you first connect to the TMC, the authentication setup page appears, where you can choose to run the TMC with authentication or without. Authentication can also be enabled/disabled in the TMC Settings panel once the TMC is running.

If you do not enable authentication, you will be directly connected to the TMC without being prompted for a login/password. Note that with authentication disabled, the TMC cannot connect to secured nodes.

If you enable authentication, an account setup page appears. Note that with authentication enabled, the TMC can connect only to secured nodes.

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

After you enter a username and password for each account, click Setup. You will be logged out, and 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>
IMAGE: The Terracotta Management Console 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.

    3. 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.

    5. 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.

    3. The connection details panel appears.

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

    4. 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). The default location, "localhost", is the machine the TMS is running on, and may not be the machine your browser is running on.

    6. 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.

    7. 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.

    8. 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.

    9. 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.

    3. The connection details panel appears. This panel displays the selected connections attributes, including whether at least basic security is enabled. The security detail is not editable.

  3. Click Edit on the connection details panel.

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

  4. Click Apply to save the edited connection or Cancel to discard changed to the 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. Connections are identified by name and location (URL). An icon next to the connection's location indicates whether at least basic security is enabled (closed lock) or if no security is in force (open lock).

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:

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 displays 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:

IMAGE: The caches table.

To view the hit rate, element count, and off-heap usage for each of a CacheManager's caches, expand that CacheManager. Each cache in the caches table also includes an icon to indicate if it distributed in a Terracotta cluster.

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.

The following statistic can be displayed for the selected item:

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 (or set the option to display all statistics), then click OK to accept the change. The table immediately begins to display the chosen statistics.

Ehcache Cache Management Panel

The Management panel displays a table listing the active CacheManagers for the selected Ehcache connection. The table's columns display the following CacheManager information:

Click the arrowhead next to a CacheManager name in the table to expand a nested table listing all of that CacheManager's caches. IMAGE: The Ehcache Management Panel The table's columns display the following attributes and metrics:

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. IMAGE: The Ehcache Diagnostics Panel 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:

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:

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.

Settings

Click Settings to open a dialog where global TMC settings can be configured.

Use Polling Interval Seconds to set the granularity of polled statistical data. Note that shorter polling intervals can have a greater effect on the overall performance of the nodes being polled.

Use the Authentication Enabled checkbox to enable or disable authentication. If you enable authentication and confirm your choice, the TMC displays the account setup page. Connections to unsecured nodes may be lost. If you disable authentication, connections to secured nodes may be lost.

To reset all settings to default values, click Reset to Defaults.