Please be aware that you are viewing our bleeding edge unstable documentation. Unless you wanted to view the bleeding edge (and possibly unstable) documentation, we recommend you use our stable docs.

Go to Ably's stable canonical documentation »

I know what I'm doing, let me see the bleeding edge docs »

You are viewing our bleeding edge unstable documentation. We recommend you use our stable documentation »
Fork me on GitHub

Application Statistics

The Ably system can be queried to obtain usage statistics for a given application, and results are provided aggregated across all channels in use in the application in the specified period. Stats may be used to track usage against account quotas. The details on how to retrieve statistics are available in the REST API documentation, Realtime client library statistics documentation and REST client library statistics documentation.

Statistics returned from the API are sparse; this means that if a metric object such as a message count { count: [val], data: val } is empty or contains only zero values for all key value pairs, then the metric will be omitted completely from the JSON response. This reduces the size of the JSON significantly and thus improves performance.

Complete stats example containing all possible metrics

Example request:

curl https://rest.ably.io/stats?unit=hour \
 -u "{{API_KEY}}"

Example response:

[
  {
    "all": {          // aggregates inbound and outbound messages
      "messages": {     // messages published on channels
        "count": 22,      // count of messages
        "data": 308       // total data in bytes
      },
      "presence": {     // presence events such as enter/leave
        "count": 41,      // count of presence events
        "data": 2873      // total data in bytes for presence events
      },
      "all": {          // aggregated messages and presence
        "count": 63,      // count of all
        "data": 3181      // total bytes for all
      }
    },
    "inbound": {      // all inbound messages i.e. received by Ably from clients
      "realtime": {     // received over realtime socket connection
        "messages": {     // messages published on channels
          "count": 0,       // count of messages
          "data": 0         // total data in bytes
        },
        "presence": {     // presence events such as enter/leave
          "count": 4,       // count of presence events
          "data": 676       // total data in bytes for presence events
        },
        "all": {          // aggregated channel messages + presence
          "count": 4,       // count of all
          "data": 676       // total bytes for all
        }
      },
      "rest": {         // received via the HTTP REST API
        "messages": {     // messages published on channels
          "count": 5,       // count of messages
          "data": 70        // total data in bytes
        },
        "presence": {     // presence events such as enter/leave
          "count": 2,       // count of presence events
          "data": 20        // total data in bytes for presence events
        },
        "all": {          // channel messages + presence
          "count": 5,       // count of all
          "data": 70        // total bytes for all
        }
      },
      "all": {          // aggregates all inbound realtime and REST messages
        "messages": {     // messages published on channels
          "count": 5,       // count of messages
          "data": 70        // total data in bytes
        },
        "presence": {   // presence events such as enter/leave
          "count": 6,     // count of presence events
          "data": 696     // total data in bytes for presence events
        },
        "all": {        // aggregated channel messages + presence
          "count": 11,     // count of all
          "data": 766     // total bytes for all
        }
      }
    },
    "outbound": {     // all outbound messages i.e. sent from Ably to clients
      "realtime": {     // sent over realtime socket connection
        "messages": {     // messages published on channels
          "count": 17,      // count of messages
          "data": 2873      // total data in bytes
        },
        "presence": {     // presence events such as enter/leave
          "count": 37,      // count of presence events
          "data": 2197      // total data in bytes for presence events
        },
        "all": {          // aggregated channel messages + presence
          "count": 54,      // count of all
          "data": 2435      // total bytes for all
        }
      },
      "rest": {         // retrieved using REST history API
        "messages": {     // messages on channels
          "count": 2,       // count of messages
          "data": 20         // total data in bytes
        },
        "presence": {     // presence events such as enter/leave
          "count": 4,       // count of presence events
          "data": 40         // total data in bytes for presence events
        },
        "all": {          // aggregated channel messages + presence
          "count": 6,       // count of all
          "data": 60         // total bytes for all
        }
      },
      "webhook": {      // messages pushed to customer's servers via WebHooks
        "messages": {     // messages published on channels
          "count": 1,       // count of messages
          "data": 10         // total data in bytes
        },
        "presence": {     // presence events such as enter/leave
          "count": 2,       // count of presence events
          "data": 20         // total data in bytes for presence events
        },
        "all": {          // aggregated channel messages + presence
          "count": 3,       // count of all
          "data": 30         // total bytes for all
        }
      },
      "all": {          // aggregates all outbound realtime, REST and WebHook messages
        "messages": {     // messages published on channels
          "count": 30,      // count of messages
          "data": 268       // total data in bytes
        },
        "presence": {     // presence events such as enter/leave
          "count": 42,      // count of presence events
          "data": 2257      // total data in bytes for presence events
        },
        "all": {          // aggregated channel messages + presence
          "count": 63,      // count of all
          "data": 2525      // total bytes for all
        }
      }
    },
    "persisted": {    // all message types persisted based on configured channel rules
      "messages": {     // messages persisted on channels
        "count": 5,       // count of messages
        "data": 70        // total data in bytes
      },
      "presence": {     // presence events persisted for states such as enter/leave
        "count": 8,       // count of presence events
        "data": 676       // total data in bytes for presence events
      },
      "all": {          // aggregated channel messages + presence persisted
        "count": 13,      // count of all
        "data": 746       // total bytes for all
      }
    },
    "connections": {  // connection statistics for this time period
      "plain": {        // non-TLS un-encrypted connections
        "peak": 4,        // peak concurrent connections for this period
        "min": 0,         // minimum concurrent connections in this period
        "mean": 2,        // average concurrent connections in this period
        "opened": 6,      // count of new connections in this period
        "refused": 0      // count of connections refused by Ably in this period
      },
      "tls": {          // TLS encrypted connections
        "peak": 2,        // peak concurrent connections for this period
        "min": 2,         // minimum concurrent connections in this period
        "mean": 2,        // average concurrent connections in this period
        "opened": 2,      // count of new connections in this period
        "refused": 0      // count of connections refused by Ably in this period
      },
      "all": {          // aggregated summary of all connection types
        "peak": 6,        // peak concurrent connections for this period
        "min": 2,         // minimum concurrent connections in this period
        "mean": 4,        // average concurrent connections in this period
        "opened": 8,      // count of new connections in this period
        "refused": 0      // count of connections refused by Ably in this period
      }
    },
    "channels": {     // channel statistics for this time period
      "peak": 2,        // peak number of channels active for this period
      "min": 0,         // min number of channels active for this period
      "mean": 0,        // average number of channels active for this period
      "opened": 0,      // total number of channels opened in this period
      "refused": 0      // number of channel attach requests failed because of permissions
    },
    "apiRequests": {  // API requests made via the REST API excluding tokens
      "succeeded": 11,  // successful requests
      "failed": 0,      // failed requests
      "refused": 0      // requests refused as a result of exceeding account limits
    },
    "tokenRequests": { // token requests via the REST API
      "succeeded": 9,   // successful tokens issued
      "failed": 0,      // failed token request
      "refused": 0      // requests refused due to permissions or rate limiting
    },
    "inProgress": "2015-03-16:10:57", // last sub-interval included in this statistic
    "count": 116,     // number of lower-level stats used to aggregate these results
    "unit": "hour",   // unit of time for these stats from the intervalId forwards
    "intervalId": "2015-03-16:10" // time period for stats in format yyyy-mm-dd:hh:mm:ss
  }
]

Sparse stats example containing present metrics

Example request:

curl https://rest.ably.io/stats?unit=minute \
 -u "{{API_KEY}}"

Example response:

[
  {
    "all": {
      "messages": {
        "count": 1,
        "data": 50
      }
      "all": {
        "count": 1,
        "data": 50
      }
    },
    "inbound": {
      "rest": {
        "messages": {
          "count": 1,
          "data": 50
        },
        "all": {
          "count": 1,
          "data": 50
        }
      },
      "all": {
        "messages": {
          "count": 1,
          "data": 50
        },
        "all": {
          "count": 1,
          "data": 50
        }
      }
    },
    "count": 0,
    "unit": "minute",
    "intervalId": "2015-03-26:01:11"
  }
]

Back to top