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:

MetricDescription
connectionsThe number of connections
publishersThe number of connections that are authorized to publish
subscribersThe number of connections that are authorized to subscribe to messages
presenceSubscribersThe number of connections that are authorized to subscribe to presence messages
presenceConnectionsThe number of connections that are authorized to enter members into the presence channel
presenceMembersThe number of members currently entered into the presence channel
objectPublishersThe number of connections that are authorized to publish updates to objects on the channel
objectSubscribersThe 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:

JSON

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:

JSON

1

2

3

4

5

6

7

{
  data: {
    metrics: {
      connections: 1,
    }
  },
}

Retrieve channel occupancy

Occupancy can be retrieved in the following ways:

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.

Select...