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.

Metachannels

The following is a list of available metachannels:

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:

{"[meta]*":["subscribe"]}

Connection lifecycle events

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

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

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

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:

const channel = ably.channels.get('[meta]channel.lifecycle');

await channel.subscribe((msg) => {
    console.log('Event type: ' + msg.name, msg.data);
});

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

const channel = ably.channels.get('[meta]channel.lifecycle');

await channel.subscribe('channel.closed', (msg) => {
    console.log('lifecycle meta channel (closed): ', msg.data);
});

Log events

The [meta]log and [meta]log:push metachannels publish events that aren't otherwise available to clients.

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.

The following example subscribes to the [meta]log channel:

const channel = realtime.channels.get('[meta]log');
channel.subscribe(msg => console.log(msg));

App statistics events

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:

const channel = ably.channels.get("[meta]stats:minute");

await channel.subscribe('update', event => {
  console.log(JSON.stringify(event, undefined, 2));
});

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:

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

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

App statistics event format

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
    }
  }
}

The following are the event properties:

Sampled connection and request events

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:

const channel = ably.channels.get('[meta]clientEvents:connections');

await channel.subscribe('connection.opened', (msg) => {
    console.log('connection opened: ', msg.data);
});

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

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);
});

Sample rate

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.

Connections

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:

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

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
}

API requests

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:

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

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"
  ]
}