Clustered REST

The Clustered REST API is exposed from the Management Center to allow you to monitor clustered statistics of distributed objects.

Enabling Clustered REST

To enable Clustered REST on your Management Center, pass the following system property at startup. This property is disabled by default.

-Dhazelcast.mc.rest.enabled=true

Clustered REST API Root

The entry point for the Clustered REST API is /rest/. This resource does not have any attributes.

All parameters that are used in the REST API URLs, like cluster names and distributed data structure names, must be URL encoded when composing a valid request for Clustered REST. Such parameters are marked in braces ({ and }) in the URL description for each endpoint. As an example, name.with/special@chars parameter value would be encoded as name.with%2Fspecial%40chars.
All endpoints return HTTP status code 404 if no data about a cluster, member, client or data structure can be found in the Management Center.

Retrieving Management Center License Expiration Time

This endpoint returns the expiration time in milliseconds (since epoch) of the license key assigned for the Management Center. Returns -1 if no license is assigned.

  • Request Type: GET

  • URL: /rest/license

  • Request:

    curl http://localhost:8080/rest/license
  • Response: 200 (application/json)

  • Body:

    {
      "licenseExpirationTime": 4099755599515
    }

Clusters Resource

This resource returns a list of clusters that are connected to the Management Center.

  • Request Type: GET

  • URL: /rest/clusters

  • Request:

    curl http://localhost:8080/rest/clusters
  • Response: 200 (application/json)

  • Body:

    ["dev", "qa"]

Cluster Resource

This resource returns information related to the provided cluster name; address of the oldest cluster member, the expiration time in milliseconds (since epoch) of the license key assigned for the cluster and the cluster type (IMDG or JET). It returns -1 for license expiration time if no license is assigned.

  • Request Type: GET

  • URL: /rest/clusters/<clustername>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/
  • Response: 200 (application/json)

  • Body:

    {
      "masterAddress": "192.168.2.78:5701",
      "licenseExpirationTime": 4099755599515,
      "clusterType": "IMDG"
    }

Members Resource

This resource returns a list of the members belonging to the provided clusters.

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members
  • Response: 200 (application/json)

  • Body:

    [
      "192.168.2.78:5701",
      "192.168.2.78:5702",
      "192.168.2.78:5703",
      "192.168.2.78:5704"
    ]

Member Resource

This resource returns the following information related to the provided member:

See the following example responses for each of the above.

Retrieving Member Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "address": "192.168.2.78:5701",
      "uuid": "11adba52-e19d-4407-a9e9-e0a271cef14a",
      "cpMemberUuid": "f5a8f8a4-f278-4a13-a23e-5accf5b02f42",
      "maxHeapMemory": 129957888,
      "ownedPartitionCount": 68,
      "usedHeapMemory": 60688784,
      "freeHeapMemory": 24311408,
      "committedHeapMemory": 85000192,
      "connectedClientCount": 1,
      "master": true
    }

Retrieving Connection Manager Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>/connectionManager

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701/connectionManager
  • Response: 200 (application/json)

  • Body:

    {
      "clientConnectionCount": 2,
      "activeConnectionCount": 5,
      "connectionCount": 5
    }

Retrieving Operation Service Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>/operationService

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701/operationService
  • Response: 200 (application/json)

  • Body:

    {
      "responseQueueSize": 0,
      "operationExecutorQueueSize": 0,
      "runningOperationsCount": 0,
      "remoteOperationCount": 1,
      "executedOperationCount": 461139,
      "operationThreadCount": 8
    }

Retrieving Event Service Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>/eventService

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701/eventService
  • Response: 200 (application/json)

  • Body:

    {
      "eventThreadCount": 5,
      "eventQueueCapacity": 1000000,
      "eventQueueSize": 0
    }

Retrieving Partition Service Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>/partitionService

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701/partitionService
  • Response: 200 (application/json)

  • Body:

    {
      "partitionCount": 271,
      "activePartitionCount": 68
    }

Retrieving Proxy Service Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>/proxyService

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701/proxyService
  • Response: 200 (application/json)

  • Body:

    {
      "proxyCount": 8,
      "createdCount": 13,
      "destroyedCount": 5
    }

Retrieving the list of all Managed Executors:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>/managedExecutors

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701/managedExecutors
  • Response: 200 (application/json)

  • Body:

    ["hz:system", "hz:async", "hz:scheduled", "hz:client", "hz:client-query", "hz:client-blocking-tasks",
    "hz:query", "hz:io", "hz:offloadable", "hz:map-load", "hz:map-loadAllKeys", "hz:mc"]

Retrieving information of a single Managed Executor:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/members/<member>/managedExecutors/<managedExecutor>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/members/192.168.2.78:5701
    	  /managedExecutors/hz:system
  • Response: 200 (application/json)

  • Body:

    {
      "name": "hz:system",
      "queueSize": 0,
      "poolSize": 0,
      "remainingQueueCapacity": 2147483647,
      "maximumPoolSize": 4,
      "completedTaskCount": 12
    }

Client Endpoints Resource

This resource returns a list of the client endpoints belonging to the provided cluster. Consider using the newly added Client Statistics Resource as it contains more detailed information about the clients.

Retrieving the list of Client Endpoints:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/clients

  • Request:

    curl http://localhost:8080/rest/clusters/dev/clients
  • Response: 200 (application/json)

  • Body:

    ["192.168.2.78:61708"]

Retrieving Client Endpoint Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/clients/<client>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/clients/192.168.2.78:61708
  • Response: 200 (application/json)

  • Body:

    {
      "uuid": "6fae7af6-7a7c-4fa5-b165-cde24cf070f5",
      "address": "192.168.2.78:61708",
      "clientType": "JAVA",
      "name": "hz.client_1",
      "labels": [
        "label1"
      ],
      "ipAddress": "192.168.2.78",
      "canonicalHostName": "localhost"
    }

Maps Resource

This resource returns a list of maps belonging to the provided cluster.

Retrieving the list of Maps:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/maps

  • Request:

    curl http://localhost:8080/rest/clusters/dev/maps
  • Response: 200 (application/json)

  • Body:

    ["customers", "orders"]

Retrieving Map Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/maps/<mapname>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/maps/customers
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "customers",
      "ownedEntryCount": 5085,
      "backupEntryCount": 5076,
      "ownedEntryMemoryCost": 833940,
      "backupEntryMemoryCost": 832464,
      "heapCost": 1666668,
      "lockedEntryCount": 2,
      "dirtyEntryCount": 0,
      "hits": 602,
      "lastAccessTime": 1532689094579,
      "lastUpdateTime": 1532689094576,
      "creationTime": 1532688789256,
      "putOperationCount": 5229,
      "getOperationCount": 2162,
      "removeOperationCount": 150,
      "setOperationCount": 100,
      "otherOperationCount": 3687,
      "events": 10661,
      "maxPutLatency": 48,
      "maxGetLatency": 35,
      "maxRemoveLatency": 18034,
      "maxSetLatency": 10,
      "totalPutLatency": 1715433,
      "totalGetLatency": 945421,
      "totalRemoveLatency": 66558323,
      "totalSetLatency": 786421
    }

MultiMaps Resource

This resource returns a list of multimaps belonging to the provided cluster.

Retrieving the list of MultiMaps:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/multimaps

  • Request:

    curl http://localhost:8080/rest/clusters/dev/multimaps
  • Response: 200 (application/json)

  • Body:

    ["customerAddresses"]

Retrieving MultiMap Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/multimaps/<multimapname>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/multimaps/customerAddresses
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "customerAddresses",
      "ownedEntryCount": 4862,
      "backupEntryCount": 4860,
      "ownedEntryMemoryCost": 0,
      "backupEntryMemoryCost": 0,
      "heapCost": 0,
      "lockedEntryCount": 1,
      "dirtyEntryCount": 0,
      "hits": 22,
      "lastAccessTime": 1532689253314,
      "lastUpdateTime": 1532689252591,
      "creationTime": 1532688790593,
      "putOperationCount": 5125,
      "getOperationCount": 931,
      "removeOperationCount": 216,
      "otherOperationCount": 373570,
      "events": 0,
      "maxPutLatency": 8,
      "maxGetLatency": 1,
      "maxRemoveLatency": 18001,
      "totalPutLatency": 487805,
      "totalGetLatency": 14931,
      "totalRemoveLatency": 16388472
    }

Replicated Maps Resource

This resource returns a list of replicated maps belonging to the provided cluster.

Retrieving the list of Replicated Maps:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/replicatedmaps

  • Request:

    curl http://localhost:8080/rest/clusters/dev/replicatedmaps
  • Response: 200 (application/json)

  • Body:

    ["replicated-map-1"]

Retrieving Replicated Map Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/replicatedmaps/<replicatedmapname>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/replicatedmaps/replicated-map-1
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "replicated-map-1",
      "ownedEntryCount": 10955,
      "ownedEntryMemoryCost": 394380,
      "hits": 15,
      "lastAccessTime": 1532689312581,
      "lastUpdateTime": 1532689312581,
      "creationTime": 1532688789493,
      "putOperationCount": 11561,
      "getOperationCount": 1051,
      "removeOperationCount": 522,
      "otherOperationCount": 355552,
      "events": 6024,
      "maxPutLatency": 1,
      "maxGetLatency": 1,
      "maxRemoveLatency": 1,
      "totalPutLatency": 64,
      "totalGetLatency": 12,
      "totalRemoveLatency": 11
    }

Caches Resource

This resource returns a list of caches belonging to the provided cluster.

Retrieving the list of Caches:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/caches

  • Request:

    curl http://localhost:8080/rest/clusters/dev/caches
  • Response: 200 (application/json)

  • Body:

    ["cache-1"]

Retrieving Cache Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/caches/<cachename>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/caches/cache-1
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "cache-1",
      "creationTime": 1532688789493,
      "hits": 100,
      "misses": 11,
      "getOperationCount": 231,
      "putOperationCount": 42,
      "removeOperationCount": 1,
      "evictions": 3,
      "averageGetTime": 10.5,
      "averagePutTime": 21.12,
      "averageRemoveTime": 23,
      "lastAccessTime": 1403602693411,
      "lastUpdateTime": 1403602693411,
      "ownedEntryCount": 300
    }

Queues Resource

This resource returns a list of queues belonging to the provided cluster.

Retrieving the list of Queues:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/queues

  • Request:

    curl http://localhost:8080/rest/clusters/dev/queues
  • Response: 200 (application/json)

  • Body:

    ["messages"]

Retrieving Queue Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/queues/{queuename>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/queues/messages
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "messages",
      "ownedItemCount": 55408,
      "backupItemCount": 55408,
      "minAge": 0,
      "maxAge": 0,
      "averageAge": 0,
      "offerOperationCount": 55408,
      "rejectedOffers": 0,
      "pollOperationCount": 0,
      "emptyPolls": 0,
      "otherOperationCount": 0,
      "events": 0,
      "creationTime": 1403602694196
    }

Topics Resource

This resource returns a list of topics and reliable topics belonging to the provided cluster.

Retrieving the list of Topics:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/topics

  • Request:

    curl http://localhost:8080/rest/clusters/dev/topics
  • Response: 200 (application/json)

  • Body:

    ["news"]

Retrieving Topic Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/topics/{topicname>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/topics/news
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "news",
      "publishOperationCount": 56370,
      "receiveOperationCount": 56370,
      "creationTime": 1403602693411
    }

Retrieving the list of Reliable Topics:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/reliabletopics

  • Request:

    curl http://localhost:8080/rest/clusters/dev/reliabletopics
  • Response: 200 (application/json)

  • Body:

    ["news"]

Retrieving Reliable Topic Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/reliabletopics/<reliableTopicname>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/reliabletopics/news
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "news",
      "publishOperationCount": 56370,
      "receiveOperationCount": 56370,
      "creationTime": 1403602693411,
    }

Executors Resource

This resource returns a list of executors belonging to the provided cluster.

Retrieving the list of Executors:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/executors

  • Request:

    curl http://localhost:8080/rest/clusters/dev/executors
  • Response: 200 (application/json)

  • Body:

    ["order-executor"]

Retrieving Executor Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/executors/<executorname>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/executors/order-executor
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "order-executor",
      "creationTime": 1403602694196,
      "pendingTaskCount": 0,
      "startedTaskCount": 1241,
      "completedTaskCount": 1241,
      "cancelledTaskCount": 0,
      "totalExecutionTime": 1000,
      "totalStartLatency": 400
    }

PN Counters Resource

This resource returns a list of PN counters belonging to the provided cluster.

Retrieving the list of PN Counters:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/pncounters

  • Request:

    curl http://localhost:8080/rest/clusters/dev/pncounters
  • Response: 200 (application/json)

  • Body:

    ["order-pncounter"]

Retrieving PN Counter Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/pncounters/<pnCountername>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/pncounters/order-pncounter
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "order-pncounter",
      "creationTime": 1403602694196,
      "statsPerMember": {
        "192.168.2.78:5701": {
          "value": 1,
          "incOperationCount": 1,
          "decOperationCount": 0
        },
        "192.168.2.79:5701": {
          "value": 1,
          "incOperationCount": 0,
          "decOperationCount": 0
        }
      }
    }

Flake ID Generators Resource

This resource returns a list of flake ID generators belonging to the provided cluster.

Retrieving the list of Flake ID Generators:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/flakeidgenerators

  • Request:

    curl http://localhost:8080/rest/clusters/dev/flakeidgenerators
  • Response: 200 (application/json)

  • Body:

    ["order-idgenerator"]

Retrieving Flake ID Generator Information:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/flakeidgenerators/{flakeIdGeneratorname>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/flakeidgenerators/order-idgenerator
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "name": "order-idgenerator",
      "creationTime": 1403602694196,
      "statsPerMember": {
        "192.168.2.78:5701": {
          "batchRequests": 1,
          "idCount": 100
        },
        "192.168.2.79:5701": {
          "batchRequests": 0,
          "idCount": 0
        }
      }
    }

Client Statistics Resource

This resource returns a list of clients belonging to the provided cluster.

Retrieving the list of Client UUIDs:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/clientStats

  • Request:

    curl http://localhost:8080/rest/clusters/dev/clientStats
  • Response: 200 (application/json)

  • Body:

    [
      "f3b1e0e9-ea67-41b2-aba5-ea7480f02a93",
      "cebf4dc9-852c-4605-a181-ffe1cca371a4",
      "2371eed5-26e0-4470-92c1-41ea17110ef6",
      "139990b3-fbc0-43a8-9c12-be53913333f7",
      "d0364a1e-8665-46a8-af1d-be1af5580d07",
      "7f337f8a-3538-4b5c-8ffc-9d4ae459e956",
      "6ef9b6e5-5add-40d9-9319-ce502f55b5fc",
      "fead3a99-19de-431c-9dd0-d6ecc4a4b9c8",
      "e788e04e-2ded-4992-9d76-52c1973216e5",
      "654fc9fb-c5c1-48a0-9b69-0c129fce860f"
    ]

Retrieving Detailed Client Statistics:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/clientStats/<clientUuid>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/clientStats/2371eed5-26e0-4470-92c1-41ea17110ef6
  • Response: 200 (application/json)

  • Body:

    {
      "type": "JAVA",
      "name": "hz.client_7",
      "address": "127.0.0.1",
      "clusterConnectionTimestamp": 1507874427419,
      "enterprise": true,
      "lastStatisticsCollectionTime": 1507881309434,
      "committedVirtualMemorySize": 12976173056,
      "freePhysicalMemorySize": 3615662080,
      "freeSwapSpaceSize": 8447324160,
      "maxFileDescriptorCount": 1000000,
      "openFileDescriptorCount": 191,
      "processCpuTime": 252980000000,
      "systemLoadAverage": 83.0,
      "totalPhysicalMemorySize": 16756101120,
      "totalSwapSpaceSize": 8447324160
      "availableProcessors": 12,
      "freeHeapMemory": 135665432,
      "maxHeapMemory": 3724541952,
      "totalHeapMemory": 361234432,
      "usedHeapMemory": 225569000,
      "uptime": 6894992,
      "memberConnection": "ALL",
      "version": "UNKNOWN",
      "nearCacheStats":{
        "CACHE":{
          "cache-1":{
            "clientUuid":"805a6342-eebb-412d-aeba-21c55fadedc3",
            "creationTime":1588752664324,
            "evictions":0,
            "expirations":0,
            "hits":148,
            "misses":164,
            "ownedEntryCount":4,
            "ownedEntryMemoryCost":420,
            "lastPersistenceDuration":0,
            "lastPersistenceKeyCount":0,
            "lastPersistenceTime":0,
            "lastPersistenceWrittenBytes":0
          }
        },
        "MAP":{
          "map-1":{
            "clientUuid":"805a6342-eebb-412d-aeba-21c55fadedc3",
            "creationTime":1588752664321,
            "evictions":0,
            "expirations":0,
            "hits":92,
            "misses":116,
            "ownedEntryCount":109,
            "ownedEntryMemoryCost":7701,
            "lastPersistenceDuration":0,
            "lastPersistenceKeyCount":0,
            "lastPersistenceTime":0,
            "lastPersistenceWrittenBytes":0
          }
        }
      }
    }

WAN Publisher Resource

This resource returns information of a WAN replicated cluster’s publisher.

Retrieving WAN Publisher Statistics:

  • Request Type: GET

  • URL: /rest/clusters/<clustername>/wanStats/<wanReplication>/publishers/<publisher>

  • Request:

    curl http://localhost:8080/rest/clusters/dev/wanStats/devWanConfig/publishers/devPublisher
  • Response: 200 (application/json)

  • Body:

    {
      "cluster": "dev",
      "configName": "devWanConfig",
      "publisherId": "devPublisher",
      "totalPublishedEventCount": 1023,
      "totalPublishLatency": 14200,
      "outboundQueueSize": 10
    }