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.
Channel-level metadata returns information about a single channel, such as its
ChannelDetails. This includes information about a channel’s occupancy.
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.
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.