Special Resource Locations

Edit online

Certain resource locations provide specific monitoring and administration services.

Discovery

A "discovery" URI format uses the path /agents/info. Used with a Terracotta Management Server (TMS), this URI returns metadata on all agents known (through configuration) to that TMS. Used with an embedded web service, metadata on that agent is returned (or a 404 if that agent is not reachable). For more information about discovery URIs, refer to the examples provided in Discover All Known Agents.

Viewing Configuration

A URI format for viewing the configuration of CacheManagers and caches uses the path agents/cacheManagers or agents/cacheManagers/caches. Agents, cacheManagers, and caches can be specified using IDs and names. The data is returned in its native XML format.

To get the configuration of one or more CacheManagers, use the following format:

/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={ 
comma_sep_cache_manager_names}]/configs
Note: If no client IDs are specified in the request, all of the clients' cacheManagers are returned. However, if no client IDs are specified in the request and the number of clients is more than the default maximum of 64, an error is returned in the JSON response. The JVM argument com.terracotta.agent.defaultMaxClientsToDisplay can be used to change the maximum number of clients to display.

To get the configuration of one or more caches, use the following format:

/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={ 
comma_sep_cache_manager_names}]/caches[;names={comma_sep_cache_names}/configs

Setting Configuration

Cache resource locations can also be specified for setting specific cache-configuration attributes using resource representations. The following is a comprehensive list of the attributes that can be set:

  • enabled – A boolean for enabling (true, DEFAULT) or disabling (false) cache operations. For example, to disable a cache's operation: PUT {"enabled":true}.

  • statsEnabled – A boolean for enabling (true) or disabling (false, DEFAULT) the gathering of cache statistics.

  • sampledStatsEnabled – A boolean for enabling (true) or disabling (false, DEFAULT) the sampling of cache statistics.

Probing a New Connection URI

To probe the existence of an agent at a given location, use an URL with the following format:

    http://127.0.0.1:9889/tmc/api/agents/probeUrl/$urlToProbe

For example, the following should return information about the REST agent running at the given address (localhost:4343):

http://127.0.0.1:9889/tmc/api/agents/probeUrl 
   /http%253A%252F%252Flocalhost%253A4343

If the agent is available, a (status code 200 AgentMetadataEntity) response similar to the following is returned:

    {"agentId":"embedded","agencyOf":"Ehcache","available":true,"secured":false, 
"sslEnabled":false,"needClientAuth":false,"licensed":false,"sampleHistorySize" 
:8640,"sampleIntervalSeconds":10,"enabled":false,"restAPIVersion":"2.7.0"}

If not available, the status code should be "204 No Content".

Getting the authentication status

The authentication status is saved in the properties file ${user.home}/.tc/mgmt/settings.ini. There is a REST resource to view the status (authentication on or off).

To GET the authentication status, use the following URI:

http://localhost:9889/tmc/api/config/settings/authentication

Either "true" or "false" is returned.

Note that to change the authentication status or settings, you must do it through the Terracotta Management Console.