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.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec');
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.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec');
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.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec')
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.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec");
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.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec");
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.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec"];
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.3EpxIQ:_MO9NOkZtcqgMGjQN0SpfhCeWMg905nwI24Q6aG3oec")
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 objectHashARTStatsQueryStatsRequestParamsParam[] 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 or Time or time in milliseconds since the epoch for any stats retrieved
Type: LongInt or @TimeDateTimeOffset

end:endEnd

current time latest DateTimeOffset or Time or time in milliseconds since the epoch for any stats retrieved
Type: LongInt or @TimeDateTimeOffset

direction:directionDirection

backwards :forwards or :backwards
Type: StringSymbolDirection 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: StringARTStatsGranularitySymbolStatsIntervalGranularity enum

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, :monthMinute, Hour, Day, MonthStatGranularityDay, StatGranularityMonth'minute', 'hour', 'day', 'month'.
Type: Stats::GRANULARITYStatsIntervalGranularity enumARTStatsGranularityString

interval_granularityintervalGranularity

Deprecated alias for unit; scheduled to be removed in version 2.x client library versions.
Type: Stats::GRANULARITYStatsIntervalGranularity enumARTStatsGranularityString

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 a Stats object whose unit is day would indicate that the period covered is “2018-03-01:10 .. 2018-03-01:11”. All Stats objects, except those whose unit is minute, 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 the unit by looking at the resolution of the intervalId. 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 TimeDateTimeDateTimeOffset object representing the parsed intervalIdinterval_idIntervalId (the UTC time at which the time period covered by this Stats object starts)
Type: TimeDateTimeDateTimeOffset

allAll

aggregate count of both inbound and outbound 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, organized into 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, organized into 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

ARTStatsGranularityStatsIntervalGranularity

typedef NS_ENUM(NSUInteger, ARTStatsGranularity) {
    ARTStatsGranularityMinute,
    ARTStatsGranularityHour,
    ARTStatsGranularityDay,
    ARTStatsGranularityMonth
};

enum ARTStatsGranularity : UInt {
    case Minute
    case Hour
    case Day
    case Month
}

public enum StatsGranularity
{
    Minute,
    Hour,
    Day,
    Month
}

io.ably.lib.types.Param