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

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('{{API_KEY}}');
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('{{API_KEY}}');
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('{{API_KEY}}')
realtime.stats(unit: 'hour') do |result_page|
  this_hour = result_page.items.first
  puts this_hour # => #<Ably::Models::Stat:…
end
AblyRealtime realtime = new AblyRealtime("{{API_KEY}}");
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);
var realtime = new AblyRealtime("{{API_KEY}}");
var query = new StatsRequestParams() { By = StatsIntervalGranularity.Hour };
var results = await realtime.StatsAsync(query);
Stats thisHour = results.Items[0];
Console.WriteLine("Published this hour " + thisHour.Inbound.All.All);
ARTRealtime *realtime = [[ARTRealtime alloc] initWithKey:@"{{API_KEY}}"];
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: "{{API_KEY}}")
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

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.

Stats objectARTStatsio.ably.lib.types.StatsAbly::Models::StatsIO.Ably.Stats

A Stats object represents a application statistic 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

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 channels for TLS and non-TLS connections
Type: ConnectionTypes
inboundInbound
statistics such as count and data for all inbound messages received over REST and Realtime connection, broken down by normal channel messages or presence messages
Type: MessageTraffic
interval_granularityIntervalGranularity
A GRANULARITY constantvalueEnum representing the granularity (interval) of this statistic such as :minute, :hour, :day, :month'minute', 'hour', 'day', 'month'Minute, Hour, Day, Month.
Type: Stats::GRANULARITYStringStatsIntervalGranularity enum
intervalIdinterval_idIntervalId
the interval ID provides both the time from which the interval starts as well as the length of time that this statistic covers i.e. the period of time which the stats are aggregated for. For example, an interval ID value of “2016-03-01:10:02” represents a single minute interval for the UTC time presented in the string. However, an interval ID of “2016-03” represents a month interval for the entire month of March 2016 based on UTC time.
Type: String
interval_timeIntervalTime
A TimeDateTimeDateTimeOffset object representing the start of the interval
Type: TimeDateTimeDateTimeOffset
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 Token requests received via the Ably REST API.
Type: RequestCount

IO.Ably.StatsRequestParams

HistoryRequestParams is a type that encapsulates the parameters for a history queries. For example usage see Channel#historyChannel#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 or Backwards
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

Back to top