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

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 } }, encoding: null, extras: undefined, size: undefined }
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, } }, }
Copied!

Occupancy can be retrieved in the following ways:

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.

Occupancy metric categories