Change Data Capture Developer Guide

Change Data Capture
Keep Your External Data Current with Change Data Capture
Change Event Message Structure
Merged Change Events
Other Types of Change Events: Gap and Overflow Events
Subscribe to Change Events
Monitor Change Event Publishing and Delivery Usage
Security Considerations
Change Event Considerations
General Considerations
Change Data Capture Allocations
Standard Object Notes
Change Events for Fields
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Change Data Capture Allocations

Learn about the allocations for change events including the number custom channels, selected entities in a channel, and event delivery.

Concurrent Client Allocation

Description Performance and Unlimited Editions Enterprise Edition Developer Edition
Maximum number of concurrent CometD clients (subscribers) across all channels and for all event types 2,000 1,000 20

The concurrent client allocation applies to CometD and to all types of events: platform events, change events, PushTopic events, and generic events. The empApi Lightning component uses CometD and consumes the concurrent client allocation like any other CometD client. Each logged-in user using empApi counts as one concurrent client. If the user has multiple browser tabs using empApi, the streaming connection is shared and is counted as one client for that user. A client that exceeds the concurrent client allocation receives an error and can't subscribe. When one of the clients disconnects and a connection is available, the new client can subscribe. For more information, see Streaming API Error Codes in the Streaming API Developer Guide.

Note

Default Allocations

If your org has no add-on licenses, default allocations apply and can't be exceeded. Each Salesforce edition provides a default allocation for the number of events delivered to CometD and Pub/Sub API clients, empApi Lightning components, and event relays. This allocation doesn’t apply to non-API subscribers, such as Apex triggers, flows, and processes. The default allocation is enforced daily to ensure fair sharing of resources in the multitenant environment and to protect the service. Default allocations aren’t part of the usage-based entitlement.

The number of delivered events to clients is counted for each subscribed client, including event relays. If you have multiple client subscribers, your usage is added across all subscribers. For example, you have an Unlimited Edition org with a default allocation of 50,000 events in a 24-hour period. Within a few hours, 20,000 event messages are delivered to two subscribed clients. So you consumed 40,000 events and are still entitled to 10,000 events within the 24-hour period.

If you exceed the default event delivery allocation in a CometD client, you receive this error: 403::Organization total events daily limit exceeded. The error is returned in the Bayeux /meta/connect channel when a CometD subscriber first connects or in an existing subscriber connection. For more information, see Streaming API Error Codes in the Streaming API Developer Guide. If you exceed the default event delivery allocation in a Pub/Sub API client, you receive this error code: sfdc.platform.eventbus.grpc.subscription.limit.exceeded and this error message: You have exceeded the event delivery limit for your org. Event messages that are generated after exceeding the allocation are stored in the event bus. You can retrieve stored event messages as long as they are within the retention window of 72 hours.

Table 1. Default Allocations
Description Performance and Unlimited Editions Enterprise Edition Developer Edition
Maximum number of entities, including standard and custom objects, that you can select for Change Data Capture on the default standard channel or a custom channel.

If the same entity is selected in multiple channels, it’s counted once toward the allocation.

 5 5 5
Maximum number of custom channels 100 100 100
Event Delivery: maximum number of delivered event notifications in the last 24 hours, shared by all clients. (Applies to CometD and Pub/Sub API clients, empApi Lightning components, and event relays only.) 50,000 25,000 10,000

Salesforce publishes change events in response to record changes, so it doesn’t enforce a publishing limit for Change Data Capture because users don’t control the total events published.

Note

Get the Number of Selected Entities

To verify the current usage of selected entities, perform this Tooling API query through REST or in the Developer Console Query Editor.

The query gets the number of unique entities selected across all channels. For more information about the Tooling API query REST resource, see REST Resources in the Tooling API Developer Guide.

The SelectedEntity field of PlatformEventChannelMember in Metadata API and Tooling API represents the entities selected through the user interface or the API. For more information, see Select Objects for Change Notifications with Metadata API and Tooling API.

Selected Entities Allocation and AppExchange Released Managed Packages

The maximum number of entity selections of 5 applies to selections that you make, or selections made by an unmanaged or managed package, except for AppExchange packages. If you install an AppExchange released managed package, the selections made by the AppExchange package don’t count against your org’s allocation. You can install the AppExchange package even if the org reaches the maximum number of selected entities default allocation. Also, installing the AppExchange package doesn’t alter the current usage for the number of selected entities. This statement holds true for first- and second-generation packages. For package developers, the entity selection allocation is still enforced in the package development org.

Change Data Capture Add-On License and Usage-Based Entitlement

To remove the limit on the number of entities that you can select for change notifications, contact Salesforce to purchase the Change Data Capture add-on license.

If your org has the add-on license, your allocation for delivered events to CometD and Pub/Sub API clients, empApi Lightning components, and event relays moves to a monthly entitlement model. The add-on increases the 24-hour allocation of delivered event notifications by 100,000 per day (3 million a month) as a usage-based entitlement. The entitlement gives you flexibility in how you use your allocations. The entitlement isn’t as strictly enforced as the default allocation. With the entitlement, you can exceed your 24-hour event delivery allocation by a certain amount. The entitlement is reset every month after your contract start date. Entitlement usage is computed only for production orgs. It isn't available in sandbox or trial orgs. For more information, see Usage-based Entitlement Fields.

Salesforce monitors event overages based on a calendar month, starting with your contract start date. If you exceed the monthly entitlement, Salesforce contacts you to discuss your event usage needs. The entitlement used for monitoring monthly event overages is the daily allocation multiplied by 30.

Table 2. Example: Entitlement with One Change Data Capture Add-On License
Description Performance and Unlimited Editions Enterprise Edition
Maximum number of entities, including standard and custom objects, that you can select for Change Data Capture. No limit No limit
Event Delivery: entitlement for delivered event notifications, shared by all clients. (Applies to CometD and Pub/Sub API clients, empApi Lightning components, and event relays only.)

You can exceed this entitlement by a certain amount before receiving an error. Salesforce uses the monthly entitlement for event overage monitoring. The monthly entitlement is returned in the limits REST API resource.

 Last 24 hours: 150,000 (50 K included with org license + 100 K from add-on license)

Monthly entitlement: 4.5 million (1.5 million included with org license + 3 million from add-on license)

 Last 24 hours: 125,000 (25 K included with org license + 100 K from add-on license)

Monthly entitlement: 3.75 million (0.75 million included with org license + 3 million from add-on license)

To increase the entitlement for event delivery, contact Salesforce to purchase the High-Volume Platform Events add-on.

The maximum event message size that Salesforce can publish is 1 MB. If your entity has hundreds of custom fields or many long text area fields, you can reach this limit. If so, the change event message isn’t delivered and is replaced by a gap event message. For more information, see Gap Events.

  • Change events are based on platform events. The default allocations and usage-based entitlement of delivered events are shared between change events and high-volume platform events.
  • Apex change event trigger subscribers don’t count against the 24-hour event delivery limit. The number of event messages that an Apex trigger can process depends on how long the processing takes for the trigger. The longer the processing time, the longer it takes for the trigger to reach the tip of the event stream.
  • The empApi Lightning component is a CometD client. As a result, the event delivery allocation applies to the component, and it is per channel per unique browser session.

Note

Monitor Your Event Usage Against Your Allocations

Check your change event delivery usage in the user interface, which is shared with platform events. From Setup, in the Quick Find box, enter Platform Events, and then select Platform Events. The usage is shown in the Event Allocations section. The publishing usage doesn’t apply to change events.

Event allocations section

Learn about other ways to check event usage with REST API, Apex, and in the Company Information page.

Allocation Default Allocations Add-On License
Event Delivery: number of delivered event notifications to CometD and Pub/Sub API clients, empApi Lightning components, and event relays If your org hasn’t purchased the add-on, get the event delivery usage in the last 24 hours by checking the DailyDeliveredPlatformEvents value with the REST API limits resource. Or in Apex, use the System.OrgLimit class and check the DailyDeliveredPlatformEvents value. This value is updated within a few minutes after event delivery. If your org has purchased the add-on, check your usage in one of these ways.
  • In the user interface: From Setup, in the Quick Find box, enter Company Information, and then select Company Information. The usage is shown under the Usage-based Entitlements related list.
  • With the REST API limits resource: usage information is returned in MonthlyPlatformEventsUsage​Entitlement in API version 48.0 and later. This value is updated one time a day.

For more information about the limit usage values that the limits REST resource returns, see Limits and List Org Limits in the REST API Developer Guide. For more information about the Apex OrgLimit class, see OrgLimit Class in the Apex Reference Guide.

Monitor 24-Hour and Daily Event Usage with PlatformEventUsageMetric

To get usage data for event publishing for any publishing method and API client delivery for CometD, Pub/Sub API, the empApi Lightning component, and event relays, query the PlatformEventUsageMetric object. PlatformEventUsageMetric contains actual event usage data broken down by type of event for high-volume platform events and change data capture events. The usage metrics stored in PlatformEventUsageMetric are separate from the REST API limits values. The REST API limits resource returns the maximum and remaining allocations for platform events and change data capture events.

PlatformEventUsageMetric usage data is available for the last 24 hours, ending at the last hour, and for historical daily usage for the last 45 days. Use PlatformEventUsageMetric to get visibility into your usage trends.

For more information, see Monitor Change Event Publishing and Delivery Usage.

Monitor Hourly Event Delivery Usage with REST API

To monitor your org's high-volume platform event and change event delivery hourly usage, make a REST API call to the limits resource every hour. The difference between the results obtained in the last 2 hours shows how many events were delivered in the last hour.

For example, you make a call at 12:00 PM and see that you have 40,000 events remaining. Then you run the same call at 1:00 PM and see that you have 38,500 events remaining. The returned responses indicate that 1,500 events were delivered to your API subscribers between 12:00 PM and 1:00 PM.

These results are examples of the responses that a GET request to the /services/data/v56.0/limits URI returns.