Statistics
The Ably service retains usage statistics per application and per account at 1 minute intervals. Your application statistics are available programmatically through our client libraries at 1 minute intervals, or aggregated up to the hour, day, or month.
Your most recent statistics are delayed by up to 6 seconds.
Your application and account statistics are also available as graphs, tabular data or downloads in your application dashboard.
The Ably service aggregates your application statistics by minute, hour, day and month, both at an application level and at an account level. Account level statistics are not available via the client library APIs and must be viewed using your account dashboard. Your monthly quota and any potential overages are calculated using the account level statistics. Find out what happens if you exceed your package limits.
Getting started
The Ably Realtime client library provides a straightforward API for retrieving application statistics:
var realtime = new Ably.Realtime('xVLyHw.-r_CEw:Zbts7mD0sIdtrO91');
realtime.stats({ unit: 'hour' }, function(err, resultPage) {
var thisHour = resultPage.items[0];
console.log(thisHour); // => {all: a, inbound: f, outbound: f, …}
});
var realtime = new Ably.Realtime('xVLyHw.-r_CEw:Zbts7mD0sIdtrO91');
realtime.stats({ unit: 'hour' }, function(err, resultPage) {
var thisHour = resultPage.items[0];
console.log(thisHour); // => {all: a, inbound: f, outbound: f, …}
});
realtime = Ably::Realtime.new('xVLyHw.-r_CEw:Zbts7mD0sIdtrO91')
realtime.stats(unit: 'hour') do |result_page|
this_hour = result_page.items.first
puts this_hour # => #<Ably::Models::Stat:…
end
AblyRealtime realtime = new AblyRealtime("xVLyHw.-r_CEw:Zbts7mD0sIdtrO91");
Params options = new Param[]{ new Param("unit", "hour") }
PaginatedResult<Stats> results = realtime.stats(options);
Stats thisHour = results.items[0];
System.out.println("Published this hour " + thisHour.inbound.all.all.count);
AblyRealtime realtime = new AblyRealtime("xVLyHw.-r_CEw:Zbts7mD0sIdtrO91");
StatsRequestParams query = new StatsRequestParams() { Unit = StatsIntervalGranularity.Hour };
PaginatedResult<Stats> results = await realtime.StatsAsync(query);
Stats thisHour = results.Items[0];
Console.WriteLine("Published this hour " + thisHour.Inbound.All.All);
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"xVLyHw.-r_CEw:Zbts7mD0sIdtrO91"];
ARTStatsQuery *query = [[ARTStatsQuery alloc] init];
query.unit = ARTStatsGranularityHour;
[realtime stats:query callback:^(ARTPaginatedResult<ARTStats *> *result, ARTErrorInfo *error) {
ARTStats *thisHour = result.items[0];
NSLog(@"Published this hour %lu", thisHour.inbound.all.all.count);
} error:nil];
let realtime = ARTRealtime(key: "xVLyHw.-r_CEw:Zbts7mD0sIdtrO91")
let query = ARTStatsQuery()
query.unit = .Hour
try! realtime.stats(query) { results, error in
let thisHour = results!.items[0]
print("Published this hour \(thisHour.inbound.all.all.count)")
}
Note that all examples on this page assume you are running them within an EventMachine reactor. Find out more in our Realtime usage documentation.
Realtime API Reference
stats
stats(Object options, callback(ErrorInfo err, PaginatedResult<Stats> results))Deferrable stats(Hash options) → yields PaginatedResult<Stats>PaginatedResult<Stats> stats(Param[] options)stats(query: ARTStatsQuery?, callback: (ARTPaginatedResult<ARTStats>?, ARTErrorInfo?) → Void) throwsTask<PaginatedResult<Stats>> StatsAsync(StatsRequestParams query)
This call queries the REST /stats
API and retrieves your application’s usage statistics. A PaginatedResult is returned, containing an array of Stats for the first page of results. PaginatedResult objects are iterable providing a means to page through historical statistics. See an example set of raw stats returned via the REST API.
Parameters
- optionsquery
- an optional objectHash
ARTStatsQuery
StatsRequestParams
Param
[] array containing the query parameters
- callback
- is a function of the form:
function(err, result)
- &block
- yields a
PaginatedResult<Stats>
object - callback
- called with a ARTPaginatedResult<ARTStats> object or an error
options
parametersARTStatsQuery
propertiesStatsRequestParams
properties
The following options, as defined in the REST /stats
API endpoint, are permitted:
- start:startStart
-
beginning of time earliest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any stats retrieved
Type:Long
Int or @Time
DateTimeOffset
- end:endEnd
-
current time latest
DateTimeOffset
orTime
or time in milliseconds since the epoch for any stats retrieved
Type:Long
Int or @Time
DateTimeOffset
- direction:directionDirection
-
backwards
:
forwards
or:
backwards
Type:String
Symbol
Direction
enum - limit:limitLimit
-
100 maximum number of stats to retrieve up to 1,000
Type:Integer
- unit:unitUnit
-
minute
:
minute
,:
hour
,:
day
or:
month
. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query
Type:String
ARTStatsGranularity
Symbol
StatsIntervalGranularity
enum
Callback result
On success, result
contains a PaginatedResult
encapsulating an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using next
and first
methods.
On failure to retrieve stats, err
contains an ErrorInfo
object with an error response as defined in the Ably REST API documentation.
Returns
On success, the returned PaginatedResult
encapsulates an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using next
and first
methods.
Failure to retrieve the stats will raise an AblyException
Returns
Returns a Task<PaginatedResult>
which needs to be awaited.
On success, the returned PaginatedResult
encapsulates an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using NextAsync
and FirstAsync
methods.
Failure to retrieve the stats will raise an AblyException
Returns
A Deferrable
object is returned from the stats method.
On success, the registered success callbacks for the Deferrable
and any block provided to the method yields a PaginatedResult that encapsulates an array of Stats
objects corresponding to the current page of results. PaginatedResult
supports pagination using next
and first
methods.
Failure to retrieve the stats will trigger the errback callbacks of the Deferrable
with an ErrorInfo
object containing an error response as defined in the Ably REST API documentation.
Related types
Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.Stats
A Stats
object represents an application’s statistics for the specified interval and time period. Ably aggregates statistics globally for all accounts and applications, and makes these available both through our statistics API as well as your application dashboard.
Please note that most attributes of the Stats
type below contain references to further stats types. This documentation is not exhaustive for all stats types, and as such, links to the stats types below will take you to the Ruby library stats documentation which contains exhaustive stats documentation. Ruby and Python however uses under_score
case instead of the default camelCase
in most languages, so please bear that in mind.
PropertiesMembersAttributesKeyword arguments
- unit
- the length of the interval that this statistic covers, such as
:minute
,:hour
,:day
,:month
Minute
,Hour
,Day
,Month
StatGranularityDay
,StatGranularityMonth
'minute'
,'hour'
,'day'
,'month'
.
Type:Stats::GRANULARITY
StatsIntervalGranularity enum
ARTStatsGranularity
String
- interval_granularityintervalGranularity
- Deprecated alias for
unit
; scheduled to be removed in version 2.x client library versions.
Type:Stats::GRANULARITY
StatsIntervalGranularity enum
ARTStatsGranularity
String
- intervalIdinterval_idIntervalId
- the UTC time at which the time period covered by this
Stats
object starts. For example, an interval ID value of “2018-03-01:10” in aStats
object whoseunit
isday
would indicate that the period covered is “2018-03-01:10 .. 2018-03-01:11”. AllStats
objects, except those whoseunit
isminute
, have an interval ID with resolution of one hour and the time period covered will always begin and end at a UTC hour boundary. For this reason it is not possible to infer theunit
by looking at the resolution of theintervalId
.Stats
objects covering an individual minute will have an interval ID indicating that time; for example “2018-03-01:10:02”.
Type:String
- interval_timeIntervalTime
- A
Time
DateTime
DateTimeOffset
object representing the parsedintervalId
interval_id
IntervalId
(the UTC time at which the time period covered by thisStats
object starts)
Type:Time
DateTime
DateTimeOffset
- allAll
- aggregate count of both
inbound
andoutbound
message stats
Type:MessageTypes
- apiRequestsapi_requestsApiRequests
- breakdown of API requests received via the Ably REST API
Type:RequestCount
- channelsChannels
- breakdown of channel related stats such as min, mean and peak channels
Type:ResourceCount
- connectionsConnections
- breakdown of connection related stats such as min, mean and peak connections for TLS and non-TLS connections
Type:ConnectionTypes
- inboundInbound
- statistics such as count and data for all inbound messages received over REST and Realtime connections, broken down by normal channel messages or presence messages
Type:MessageTraffic
- outboundOutbound
- statistics such as count and data for all outbound messages retrieved via REST history requests, received over Realtime connections, or pushed with Webhooks, broken down by normal channel messages or presence messages
Type:MessageTraffic
- persistedPersisted
- messages persisted and later retrieved via the history API
Type:MessageTypes
- tokenRequeststoken_requestsTokenRequests
- breakdown of Ably Token requests received via the Ably REST API.
Type:RequestCount
- pushPush
- Detailed stats on push notifications, see our Push documentation for more details
Type:PushStats
IO.Ably.StatsRequestParams
HistoryRequestParams
is a type that encapsulates the parameters for a history queries. For example usage see Channel#history
Channel#History
.
Members
- Start
-
null The start of the queried interval
Type:DateTimeOffset
- End
-
null The end of the queried interval
Type:DateTimeOffset
- Limit
-
null By default it is null. Limits the number of items returned by history or stats
Type:Integer
- Direction
-
Backwards Enum which is either
Forwards
orBackwards
Type:Direction
enum - ExtraParameters
- Optionally any extra query parameters that may be passed to the query. This is mainly used internally by the library to manage paging.
Type:Dictionary<string, string>
ARTStatsGranularityStatsIntervalGranularity
ARTStatsGranularity
is an enum specifying the granularity of a ARTStats interval
.
typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
ARTStatsGranularityMinute,
ARTStatsGranularityHour,
ARTStatsGranularityDay,
ARTStatsGranularityMonth
};
enum ARTStatsGranularity : UInt {
case Minute
case Hour
case Day
case Month
}
StatsIntervalGranularity
is an enum specifying the granularity of a Stats interval
.
public enum StatsGranularity
{
Minute,
Hour,
Day,
Month
}
io.ably.lib.types.Param
Param
is a type encapsulating a key/value pair. This type is used frequently in method parameters allowing key/value pairs to be used more flexible, see Channel#history
for an example.
Please note that key
and value
attributes are always strings. If an Integer
or other value type is expected, then you must coerce that type into a String
.
Members
- key
- The key value
Type:String
- value
- The value associated with the
key
Type:String