Metadata subscriptions

Realtime metadata updates are provided by subscribing to metachannels using the realtime interface of an Ably SDK. Metachannels are a namespace of channels beginning with the [meta] qualifier and they can be subscribed to in the same manner as regular channels.

Events are published to metachannels that provide app-level metadata about different resources, such as channels, connections and API requests.

The following is a list of available metachannels:

[meta]connection.lifecycle
Publishes connection lifecycle events of realtime connections.
[meta]channel.lifecycle
Publishes channel lifecycle events, such as channels opening and closing.
[meta]stats:minute
Publishes app statistics at one minute intervals.
[meta]clientEvents:connections
Publishes metadata for a sample of connection events.
[meta]clientEvents:apiRequests
Publishes metadata for a sample of API request events.
[meta]log
Publishes error events that would otherwise not be received by a client. Excludes errors related to Push Notifications.
[meta]log:push
Similar to [meta]log, but only for errors that occur during delivery of Push Notifications.

It is never possible to publish or be present on a metachannel, however you can query their history.

The following is an example of a capability that provides access to subscribe to all metachannels:

{<a href="[">[meta]*</a>"subscribe"]}
Copied!

Connection lifecycle events are published when connections are opened and closed within an app. They are published to the [meta]connection.lifecycle metachannel.

Channel lifecycle events are published when channels are opened and closed within an app.

The following events are published to [meta]channel.lifecycle:

channel.opened
indicates that the channel has been activated globally. This means that it has become active in at least one region, having previously been inactive.
channel.closed
indicates that the channel has been deactivated globally.
channel.region.active
indicates that the channel has been activated in a specific region.
channel.region.inactive
indicates that the channel has been deactivated in a specific region.

The data property of all events is a ChannelDetails object. The ChannelDetails.ChannelStatus which includes occupancy details varies depending on the event. If the event is specific to a region, such as channel.region.active then the occupancy metrics will only be for that region. For other events such as channel.opened, the occupancy metrics will be global.

The following is an example of subscribing to all [meta]channel.lifecycle events:

Select...
const channel = ably.channels.get('[meta]channel.lifecycle'); await channel.subscribe((msg) => { console.log('Event type: ' + msg.name, msg.data); });
Copied!

The following is an example of subscribing to channel.closed events:

Select...
const channel = ably.channels.get('[meta]channel.lifecycle'); await channel.subscribe('channel.closed', (msg) => { console.log('lifecycle meta channel (closed): ', msg.data); });
Copied!

The [meta]log and [meta]log:push metachannels publish events that aren’t otherwise available to clients. For example, if Ably receives an error response when delivering a webhook to your endpoint, Ably sends an event to [meta]log with information about the error.

Errors where the client can be directly notified are not published to the metachannels. For example, if a client attempts to publish a message but exceeds a channel rate limit, the client will be notified by an error callback passed to the publish() method.

[meta]log publishes errors related to all resources other than Push Notifications, which are published to [meta]log:push.

The [meta]stats:minute metachannel publishes app-level statistics at one minute intervals. This is in addition to being available in your account dashboard and to query programmatically.

Events are published every minute and contain statistics for only the past minute. They are published as an update and this is the only event name published to the metachannel.

The following is an example of subscribing to [meta]stats:minute:

Select...
const channel = ably.channels.get("[meta]stats:minute"); await channel.subscribe('update', event => { console.log(JSON.stringify(event, undefined, 2)); });
Copied!

As there could potentially be a delay of up to one minute before the first event, you can obtain the most recent statistics event using the rewind channel option.

The following example will return the most recent event and also subscribe to subsequent events:

Select...
const channel = ably.channels.get('[meta]stats:minute', {params: {rewind: '1'}});
Copied!

You can also subscribe to [meta]stats:minute using SSE.

Each event will be formatted according to the app-stats JSON schema. The following is an example of a returned event:

{ "name": "update", "id": "trVvT-KeEw:0:0", "encoding": null, "data": { "intervalId": "2021-10-07:16:23", "unit": "minute", "schema": "https://schemas.ably.com/json/app-stats-0.0.1.json", "entries": { "connections.all.peak": 1, "connections.all.min": 1, "connections.all.mean": 0.2, "connections.all.opened": 2, "apiRequests.all.succeeded": 2, "apiRequests.tokenRequests.succeeded": 2 } } }
Copied!

The following are the event properties:

name
Only update is supported as an event name.
id
The unique ID of the event.
encoding
The encoding of the event data.
intervalId
This is an indication of the date-time interval that this statistics record relates to.
unit
Only minute is supported as a statistics unit.
schema
The JSON schema used for the encoding of the event.
entries
This is a flattened representation of the categories for which there are non-zero entries for this statistics record.

Enterprise accounts can sample connection and request events in order to monitor the usage of Ably services. Events are published to two metachannels that contain metadata for a sample of connections and API requests. These events can be used to compile statistics on app usage, enabling you to perform arbitrary data processing and aggregation related to client population and client activity. These metachannels must be enabled for each app you would like to sample.

Events are published on the metachannels [meta]clientEvents:connections and [meta]clientEvents:apiRequests.

The following code snippet shows how to subscribe to connection.opened events:

Select...
const channel = ably.channels.get('[meta]clientEvents:connections'); await channel.subscribe('connection.opened', (msg) => { console.log('connection opened: ', msg.data); });
Copied!

The following code snippet shows how to subscribe to all sampled API request events:

Select...
const channel = ably.channels.get('[meta]clientEvents:apiRequests'); // To subscribe to all event types await channel.subscribe((msg) => { console.log('Event type: ' + msg.name, msg.data); });
Copied!

The rate of sampling dictates the number of events published to the metachannels. For example, a rate of 0.1% for connections would publish an average of one message in every 1000. The sample rate can be configured independently for connections and API requests within the same app.

A sample of connection events are published to the channel [meta]clientEvents:connections. Connection events can be used to compile statistics relating to client population.

The connection event types are:

connection.opened
The connection was successfully made by the client to Ably.
connection.closed
The connection was explicitly closed by the client.
connection.refused
The connection was rejected for an expected reason, such as invalid credentials or a malformed request.
connection.failed
The connection was rejected for an unexpected reason, such as a network failure.

Events contain a subset of the following metadata in the data field:

host
The host the connection was made to.Type: String
requestId
The unique ID of the request that Ably can use to correlate a connection event with internal logs, if necessary.Type: String
region
The region the connection was made from.Type: String
headers
The headers sent with the connection.Type: JSON Object
query
The parsed query string of the connection request, excluding authentication parameters. It contains connection information such as the client library version and any custom transport parameters.Type: JSON Object
connectionId
The unique ID of the connection.Type: String
clientId
The ID of the client that attempted the connection.Type: String
channels
A list of channels included in the request. This is only relevant where channels are supported as part of the connection request, such as with SSE. Type: Array
duration
The duration the connection was open for.Type: Integer
error
The details of any error encountered whilst making the connection request. It includes an error message, error code and HTTP status code.Type: JSON Object

An example of a connection.closed event is:

{ "host": "realtime.ably.io", "requestId": "fbbcb0ab-fa56-47c4-bbd4-fccc22a271b8", "region": "us-east-1", "headers": { "host": "realtime.ably.io", ... }, "query": { "format": "json", "heartbeats": "true", "v": "1.2", "lib": "js-web-1.2.9" }, "connectionId": "54321", "clientId": "12345", "duration": 61151 }
Copied!

Sampled API request events for an app are published to the channel [meta]clientEvents:apiRequests. API request events can be used to compile statistics relating to client activity.

The request event types are:

request.succeeded
The request was successful.
request.refused
The request was rejected for an expected reason, such as a malformed request or insufficient privileges.
request.failed
The request was rejected for an unexpected reason, such as a network failure.

Events contain a subset of the following metadata in the data field:

host
The host the request was made to.Type: String
requestId
The unique ID of the request that Ably can use to correlate a request event with internal logs, if necessary.Type: String
region
The region the request was made in.Type: String
headers
The headers sent with the request.Type: JSON Object
query
The details of the parsed request query, including information such as the request format.Type: JSON Object
path
The path of the endpoint called in the request, for example /channels/{channel-name}/messages.Type: String
channels
A list of channels the request was made against.Type: Array
error
The details of any error encountered whilst making the request. It includes an error message, error code and HTTP status code.Type: JSON Object

An example of a request.succeeded event is:

{ "host": "rest.ably.io", "requestId": "fbbcb0ab-fa56-47c4-bbd4-fccc22a271c9", "region": "us-east-2", "headers": { "host": "rest.ably.io", ... }, "query": { "format": "json" }, "path": "/channels/example-channel/messages", "channels": [ "my-test-channel" ] }
Copied!
Metachannels
v1.2