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.

The following are the metric categories that occupancy reports:

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

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:

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

Copy
Copied!

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:

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

Copy
Copied!

Occupancy can be retrieved in the following ways:

• In realtime, by subscribing to a channel with the occupancy channel option
• For a single channel using a REST request
• “Enumerating all active channels”#one-off-requests in an app
• Configure a channel.occupancy rule source to send occupancy events to an external target, such as AWS Lambda or a webhook

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.

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

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.