Metadata overview

Metadata provides insight into activity within an app. This activity is related to things such as connections, channels and API requests.

Metadata can be used to check if there are any subscribers on a channel before publishing to it. By monitoring channel lifecycle events publishers can know when a channel is opened, becomes active, or is no longer active. This can indicate when the last subscriber has left a channel.

Metadata can also be used to monitor the usage of Ably services for an app. Sampled connection and requests enable statistics to be compiled, and have arbitrary data processing and aggregation performed against them This can provide insight into client population and client activity.

Metadata is returned at the following levels:

• App-level data such as the lifecycle of all channels across an app
• Channel-level data such as the occupancy of an individual channel

App-level metadata returns information about a resource across a whole app, such as all connections or all channels.

Examples of app-level metadata include metachannels and enumerating all active channels via REST.

Channel-level metadata returns information about a single channel, such as its ChannelDetails. This includes information about a channel’s occupancy.

Examples of channel-level metadata include the occupancy channel option and querying a channel via REST.

Metadata can be retrieved by:

• Subscribing to metachannels to receive metadata events in realtime
• Querying metadata via REST requests
• Using a channel option to subscribe to occupancy events
• Using occupancy events as an integration source

Metachannels are a special namespace of channels, prefixed with [meta], that provide app-level metadata. An example, is [meta]channel.lifecycle which publishes events relating to channels being opened and closed across an app. A further example is [meta]stats:minute which publishes app statistics every minute.

Metadata can be queried using REST requests to return channel-level metadata for a single channel, or enumerate through all active channels in an app.

Be aware that this REST API is intended for occasional queries. If you require realtime updates Ably recommends using metachannels or an occupancy channel option rather than polling.

The occupancy channel option provides metrics about the clients attached to a channel, such as the number of connections and the number of clients subscribed to the channel. The occupancy channel option returns channel-level metadata as it can be enabled on a channel-by-channel basis.

Integrations can utilize channel occupancy events as a source.