GET and HEAD
Returns a JSON array representing the details of all specified resources, or an XML representation of data whose native format is XML.
Note: | HEAD operations return the same metadata as GET operations, but no body. |
The following GET examples are organized by task and URI.
Discover All Known Agents
/agents/info
Used with a 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.
The following is a response from a TMS that has agents "foo" and "goo" configured, and both are responding:
[{"restAPIVersion":"1.0.0","available":true,"agentId":"foo","agencyOf":"Ehcache"},
{"restAPIVersion":"1.0.0","available":true,"agentId":"goo","agencyOf":"Ehcache"}]
The following is a response from a TMS that has agents "foo" and "goo" configured, but with only "foo" responding:
[{"restAPIVersion":"1.0.0","available":true,"agentId":"foo","agencyOf":"Ehcache"},
{"restAPIVersion":null,"available":false,"agentId":"goo","agencyOf":null}]
Note that the metadata returned includes the API version running on the agent, as well as the type of client ("agencyOf") the API is serving.
With the v2 REST API, /v2/agents/info returns a response with additional information, for example:
{"agentId":"TMS","apiVersion":"v2","entities":[{"agentId":"MyCluster",
"productVersion":"4.3.0","agencyOf":"TSA",
"available":true,"secured":true,"sslEnabled":true,"needClientAuth":false,
"licensed":true,"sampleHistorySize":670,
"sampleIntervalSeconds":4,"enabled":true},
{"agentId":"MyCluster$localhost_50808","productVersion":"2.10.0",
"agencyOf":"Ehcache","available":true,"secured":true,"sslEnabled":true,
"needClientAuth":false,"licensed":true,"sampleHistorySize":30,
"sampleIntervalSeconds":1,"enabled":true}],
"exceptionEntities":[{"agentId":"MyCluster-1",
"message":"javax.ws.rs.ProcessingException:
java.net.SocketTimeoutException: connect timed out","stackTrace":
"java.util.concurrent.ExecutionException: javax.ws.rs.ProcessingException:
java.net.SocketTimeoutException: connect timed out\n\tat...
Get Details on Specific Agents
/agents;ids=client01,client02
JSON representing an array all available agent detail. If no agent IDs are included, all agents available are returned.
Get Details on Specific Caches
/agents;ids=client01/cacheManagers;names=foo/caches;names=bar
Get Configuration of Specific CacheManager
/agents;ids=client01/cacheManagers;names=foo/configs
Returns an XML representation of the CacheManager "foo". For example, the following is an XML representation returned from a standalone Ehcache node:
Certain operations can only be executed against specific targets. Specifying multiple agents, CacheManagers, or caches generate an error response (code 400).
Get Configuration of Specific Caches
/agents;ids=client01/cacheManagers;names=foo/caches;names=baz/configs
Get All CacheManager Details
/agents/cacheManagers
The following example shows a JSON object returned by this URI when the GET is executed against a standalone Ehcache node with two CacheManagers, each with one cache:
[{"name":"CM2","attributes":{"ClusterUUID":"03e505092b6a4b1a9af5d1b035a7d5ed","
Enabled":true,"HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"300M","
CacheAverageSearchTime":0,"CachePutRate":84,"CacheOnDiskHitRate":0,
"CacheMetrics":{"Cache12":[2,84,84]},
"CacheRemoveRate":0,"CacheOffHeapHitRate":0,"Searchable"
:false,"CacheOnDiskMissRate":84,"CacheNames":["Cache12"],"
TransactionRolledBackCount":0,"CacheInMemoryHitRate":2,"WriterQueueLength":0,"
CacheOffHeapMissRate":0,"Transactional":false,"CacheHitRate":2,"
TransactionCommitRate":0,"CacheExpirationRate":0,"CacheUpdateRate":0,"
MaxBytesLocalHeap":104857600,"CacheAverageGetTime":0.027891714,"
TransactionRollbackRate":0,"CacheEvictionRate":0,"CacheInMemoryMissRate":84,"
MaxBytesLocalDisk":314572800,"MaxBytesLocalOffHeapAsString":"200M","
CacheSearchRate":0,"TransactionCommittedCount":0,"TransactionTimedOutCount":0,"
Status":"STATUS_ALIVE","MaxBytesLocalOffHeap":209715200,"WriterMaxQueueSize":0,"
StatisticsEnabled":true,"MaxBytesLocalHeapAsString":"100M","CacheMissRate":84},"
agentId":"embedded","version":"1.0.0-SNAPSHOT"},{"name":"CM1","attributes":
{"ClusterUUID":"03e505092b6a4b1a9af5d1b035a7d5ed","Enabled":true,"
HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"300M","
CacheAverageSearchTime":0,"CachePutRate":166,"CacheOnDiskHitRate":8,"
CacheMetrics":{"Cache11":[7,83,83],"Cache12":[6,83,83]},"CacheRemoveRate":0,"
CacheOffHeapHitRate":0,"Searchable":false,"CacheOnDiskMissRate":166,"CacheNames"
:["Cache11","Cache12"],"TransactionRolledBackCount":0,"CacheInMemoryHitRate":5,"
WriterQueueLength":0,"CacheOffHeapMissRate":0,"Transactional":false,"
CacheHitRate":13,"TransactionCommitRate":0,"CacheExpirationRate":0,"
CacheUpdateRate":0,"MaxBytesLocalHeap":104857600,"CacheAverageGetTime":0.061820637,
"TransactionRollbackRate":0,"CacheEvictionRate":0,"CacheInMemoryMissRate":174,"
MaxBytesLocalDisk":314572800,"MaxBytesLocalOffHeapAsString":"200M","
CacheSearchRate":0,"TransactionCommittedCount":0,"TransactionTimedOutCount":0,"
Status":"STATUS_ALIVE","MaxBytesLocalOffHeap":209715200,"WriterMaxQueueSize":0,"
StatisticsEnabled":true,"MaxBytesLocalHeapAsString":"100M","CacheMissRate":166},
"agentId":"embedded","version":"1.0.0-SNAPSHOT"}]
Note: | When no client IDs are specified in the request, all of the clients' cacheManagers are returned. However, if 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. |
With the v2 REST API, /v2/agents/cacheManagers returns a response such as:
{"agentId":"TMS","apiVersion":"v2","entities":[
{"agentId":"MyCluster$localhost_50808","name":"MyCluster-1","attributes":
{"ClusterUUID":"b769bf9f44c54242a5d6eff8b1ad9dc3","Enabled":true,
"HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"0","Searchable":true,"
MaxBytesLocalDisk":0,"CacheNames":["bigMemorySample"],
"MaxBytesLocalOffHeapAsString":"4G","Status":"STATUS_ALIVE",
"MaxBytesLocalOffHeap":4000000000,"WriterMaxQueueSize":0,
"MaxBytesLocalHeapAsString":"1G","Transactional":false,"MaxBytesLocalHeap"
:1000000000}}],"exceptionEntities":[{"agentId":"MyCluster-1","message"
:"javax.ws.rs.ProcessingException: java.net.SocketTimeoutException:
connect timed out","stackTrace":...
Get Specific CacheManager Details
/agents/cacheManagers?show=CacheInMemoryHitRate&show=CacheHitRate&
show=CacheAverageGetTime
This URI returns a JSON array with only the specified statistics:
[{"name":"CM1","attributes":{"CacheAverageGetTime":0.26357448,
"CacheHitRate":47,"CacheInMemoryHitRate":3},"agentId":"embedded","version":
"1.0.0-SNAPSHOT"}]
Configuration attributes (for example, MaxBytesLocalHeap) can also be specified with the show query parameter.
Possible HTTP Status Codes for GET or HEAD
404 – Specified resource is not found.
Contact Support
|
Community
|
Feedback