Occupancy
Occupancy provides high level metrics about the clients attached to a channel. This includes the number of connections currently attached to a channel, and the number of connections attached that are permitted to publish and subscribe to the channel.
Occupancy metric categories
The following are the metric categories that occupancy reports:
| Metric | Description |
|---|---|
| connections | The number of connections |
| publishers | The number of connections that are authorized to publish |
| subscribers | The number of connections that are authorized to subscribe to messages |
| presenceSubscribers | The number of connections that are authorized to subscribe to presence messages |
| presenceConnections | The number of connections that are authorized to enter members into the presence channel |
| presenceMembers | The number of members currently entered into the presence channel |
| objectPublishers | The number of connections that are authorized to publish updates to objects on the channel |
| objectSubscribers | The number of connections that are authorized to subscribe to objects on the channel |
Occupancy payload structure
Details of a channel's occupancy are returned in the metrics property of a payload.
If occupancy is returned as a [meta]occupancy event when subscribing to a channel using the occupancy channel option, then metrics is part of the data property. The following is an example of a [meta]occupancy event:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
name: '[meta]occupancy',
id: 'V12G5ABc_M:0:0',
timestamp: 1612286351217,
clientId: undefined,
connectionId: undefined,
connectionKey: undefined,
data: {
metrics: {
connections: 1,
publishers: 1,
subscribers: 1,
presenceConnections: 1,
presenceMembers: 0,
presenceSubscribers: 1,
objectPublishers: 1,
objectSubscribers: 1
}
},
encoding: null,
extras: undefined,
size: undefined
}If occupancy is returned as part of a REST request, then metrics are within a ChannelDetails object. The following is an example of a ChannelDetails object:
1
2
3
4
5
6
7
{
data: {
metrics: {
connections: 1,
}
},
}Retrieve channel occupancy
Occupancy can be retrieved in the following ways:
- In realtime, by subscribing to a channel with the
occupancychannel option - For a single channel using a REST request
- Enumerating all active channels in an app
- Configure a
channel.occupancyrule source to send occupancy events to an external target, such as AWS Lambda or a webhook
Realtime occupancy updates
The occupancy channel option enables a client to subscribe to occupancy events related to a channel. Events are delivered to the client as messages on the channel.
One off occupancy requests
Occupancy can be queried via REST in the following ways:
- Query a single channel to return its
ChannelDetails, including its occupancy - Enumerate a list of active channels in an app, including the occupancy of each
Integrations
Integration rules can be configured with channel.occupancy set as a rule source. Occupancy events that occur on the selected channels will be pushed to external targets, such as AWS Lambda, or custom webhook endpoints.