BlackBerry Spark Communications Services Guide

Usage Statistics

On Android, iOS, and Linux, the SDK records statistics as it operates. Applications can collect these stats from the SDK and export them via any compatible statistics aggregation system. The SDK records stats that can be export by applications for offline analysis and reporting.

Stat Types

Every stat has a name property that indicates what is being measured. Some stats have a single scalar value, such as a counter, while others have multiple values. The following subsections describe the different types of stats that the SDK collects.

Counter

The simplest type of stat is the scalar integer. A scalar integer has a single count value and must be a whole number.

This type of stat is usually used for recording how many times something has happened, in which case it's referred to as a "counter".

Example Counter

The SDK does not currently record any pure counter stats, but the counter stat forms the basis of some of the other stat types. For example, a stat named addParticipant could count how many times the local endpoint has added a participant to any chat. So, if the addParticipant stat had a count of 12, that would mean that the local endpoint has added 12 participants to chats.

Aggregation of Counters

Generally, counters can be aggregated across multiple endpoints. If an application sums all of the counters with the same name from all of a user's endpoints, it can compute how many times that counted event happened on all of their endpoints.

In the above example, summing all of the addParticipant stat count values from all of a user's endpoints would compute how many times the user added a participant from any endpoint.

Likewise, if an application aggregates counters across multiple users, it can monitor the entire user population.

Counter Histogram

This stat is a collection of counters that work like a histogram. In addition to its name, this stat has a set of part and count pairs that record the label and value for each histogram bucket (i.e. each "part") of the histogram.

Only buckets with non-zero count values will be included in the histogram.

Example Counter Histogram

The stat named msg is a counter histogram that has a part for each of the message tags that have been sent by the local endpoint. The count associated with each part counts the number of times a message with that tag has been sent.

Consider the case where the msg stat has the following values:

part count
Picture 7
Text 102
File 4

This means that the local endpoint sent 7 messages that had a tag of Picture, 102 messages with a tag of Text, and 4 messages with a tag of File.

For this example stat, the set of part values that will be collected depends on the set of tag values that the application uses when sending messages.

Aggregation of Counter Histograms

Because they are a collection of counters, counter histograms can be aggregated in the same way as simple counters.

Using the example above, an application can aggregate the msg histogram to learn how many different message types a user or set of users is sending.

Size Histogram

A size histogram records information about many instances of a single type of measurement. Specifically, it is repeatedly measuring the size, in bytes, of a certain class of thing, such as a file attachment.

Like a counter histogram, this stat has a name and a collection of buckets, each with a part label and a count. However, with size histograms, each bucket represents a size milestone.

The part label of each bucket is one of a fixed set of strings such as 4K or 128M. These labels identify the largest size measurement that will be counted in the bucket. When a size measurement is made, the count of the one largest bucket whose part is greater than or equal to that measurement is incremented.

The predefined bucket part labels are described below. Note that the buckets are somewhat logarithmic, and the first set of buckets cover a smaller size range than the next set of buckets, and so on. This allows meaningful information to be captured about a large range of sizes without discarding useful detail at each particular scale.

Range Label Note
0 bytes 0K A single bucket where all zero measurements are counted
4 KB - 16 KB 4K, 8K, ..., 64K 16 buckets of 4 KB width
128 KB - 1 MB 128K, 192K, ..., 1M 15 buckets of 64 KB width
2 MB - 16 MB 2M, 3M, ..., 16M 15 buckets of 1 MB width
32 MB - 256 MB 32M, 48M, ..., 256M 15 buckets of 16 MB width
Larger than 256 MB 256M+ One bucket for outliers

For example, a measurement of 120 KB would be counted in the bucket with the part label 128K, since it is the bucket for measurements > 64 KB but <= 128 KB. A measurement of 85 MB would be recorded in the 96M bucket since 85 MB > 80 MB and 85 <= 96 MB.

Note that the kilobytes and megabytes use a traditional definition based on 1024.

Only buckets with non-zero count values will be included in the histogram.

Example Size Histogram

There is an entire set of histograms that are named using the pattern of msg.file.<tag>, where <tag> is the tag value used by the application when it sent a message. Each of these histograms measures the different sizes of file attachment that the local endpoint sent along with messages of the given tag.

For example, the msg.file.Picture histogram measures how large all of the file attachments are for the Picture-tagged messages sent by the endpoint. Consider if its buckets were recorded as follows:

part count
256K 1
2M 12
3M 44
4M 36
8M 5

This histogram records a lot of useful information about messages sent with a tag of Picture.

Firstly, because the 256K bucket has a count value of 1, we know that there was only 1 attachment that was less than or equal to 256 KB in size.

But, we also know that there were no attachments sent that were less than 192 KB, because if there were, they'd be recorded in smaller buckets (such as the 192K bucket, the 128K bucket, and so on). We don't see any such counters in those smaller buckets, so we can make this conclusion.

We know that there were 13 attachments that were less or equal to 2 MB in size: 12 in the 2M bucket and 1 in the 256K bucket. We also know that the 12 attachments in the 2M bucket were larger than 256 KB, and that they were all larger than 1 MB. Otherwise, they would have been counted in other buckets.

We also know that there were 98 attachments sent in total for messages with a tag of Picture. To compute this, we simply sum all of the bucket count values in the whole msg.file.Picture histogram.

Aggregation of Size Histograms

Like the previous stat types, instances of identically named size histograms can be aggregated across endpoints and users. By summing each bucket with the same part label, applications can form an aggregate view of the data.

As seen in the above example, this kind of histogram supports an additional kind of aggregation. Applications can sum all of the buckets in a single instance of the histogram to learn how many messages with a given tag had an attachment of any size. This is how the total of 98 was obtained, above. Applications can also sum all of the buckets in an aggregate of this type of histogram to get a total count for the set of endpoints and users that the aggregate represents.

The example also showed that sometimes this type of histogram is used to define a set of related histograms. For example, in the case of those stats with a name pattern of msg.file.<tag>, applications can also aggregate all members of this set to find the attachment sizes across all messages with all possible tags.

By aggregating across endpoints, users, buckets, and tags, applications can join and split the data in various interesting ways to find different kinds of patterns and behaviours.

Stat Collection

The SDK records stats automatically. Applications that want to use the recorded stats must collect them via the SDK's API and then export them using a mechanism of the application's choosing.

Periodically, such as once per day, the application on each endpoint should ask the SDK for its current list of recorded stats. The SDK will return all non-zero counters. The application then exports these values externally, and once that export has succeeded, it tells the SDK, which in turn resets the counters so that the next list of recorded stats will only include values that have been recorded since the previous list was collected.

Through this simple mechanism, stats also obtain a temporal aspect: the counter values collected "belong to" that specific collection period. The stats remain locked to that time period and can be analyzed later against other time periods.

Applications should capture user, endpoint, and temporal information when they collect and export stats to allow richer analysis and reporting options.

See the API Reference for each individual OS for details of how applications can perform stats collection.

Defined Stats

The following stats are recorded by the current version of the SDK. Stats may be removed or added in future releases as the implementation and behaviours of the SDK change.

Endpoint Setup Stats

The setup stat is a counter histogram that has buckets labeled with one of the following part strings.

part Description
try Endpoint setup is being started or retried.
ok Endpoint setup has completed successfully.

The setup.err stat is a counter histogram that has buckets labeled with part strings taken from the SDK endpoint setup API error reasons. This list includes the following:

part Description
TemporaryServerError There was a problem with one of the endpoint setup steps but it is possible that a retry will succeed. See the API documentation for more details.
PermanentServerError There was a serious problem with one of the endpoint setup steps. See the API documentation for more details.
Forbidden The BlackBerry Infrastructure forbids this user from registering for an undisclosed reason. The user ID provided in authToken might be unusable. See the API documentation for more details.
CertificateError There was a problem with one of the endpoint setup steps due to a certificate error. See the API documentation for more details.

REST Stats

Each of the stats described in this section are counter histograms that have buckets labeled with one of the following part strings.

part Description
try An attempt to issue the request.
ok The request was successful.
0 The request failed without a response.
401 The request encountered an authorization failure.
403 The request was forbidden.
404 The request was attempting to manipulate a non-existent object.
503 The server experienced a temporary timeout.
bbid The request was unable to obtain an authentication token.
http The request experienced some other unspecified HTTPS failure.

The REST counter histograms that use the above part values are as follows.

name Description
bus.register REST API calls that create a new endpoint.
bus.bbmToken REST API calls to turn SDK application tokens into internal tokens.
oly.uploadFile A chat attachment or other file was uploaded to BlackBerry's secure cloud storage.
oly.downloadFile A chat attachment or other file was downloaded to BlackBerry's secure cloud storage.
mailbox.create REST API calls to create a chat.
mailbox.update REST API calls to update a chat's metadata.
mailbox.lookup REST API calls to find the metadata of a chat.
mailbox.lookupAll REST API calls to lookup of all subscribed chats.
mailbox.addMember REST API calls to add the current or another user to a chat.
mailbox.removeMember REST API calls to remove the current or another user from a chat.
mailbox.addAdmin REST API calls to promote another user to a chat admin.
mailbox.removeAdmin REST API calls to demote the current or another user from being a chat admin.

Message Stats

Message Counter Histogram

The msg stat is a counter histogram that has buckets labeled with a dynamic set of part strings. Each part represents a tag from a chat message that was sent by the endpoint, so any and all tag values used by the application can appear as a part.

The count for each part records the number of messages with that tag that have been sent by the local endpoint.

Attachment Size Histograms

There is an entire set of histograms that are named using the pattern of msg.file.<tag>, where <tag> is actually the tag value used by the application when it sent a message. Each of these histograms measures the different sizes of file attachment that the local endpoint sent along with messages of the given tag.

There is another set of histograms that are named using the pattern of msg.thumb.<tag> that measures the sizes of thumb attachments on each message sent by the local endpoint.

See the example of msg.file.Picture above for a detailed discussion of these histograms.