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
Standard Object Notes
Change Events for Fields
PDF

Newer Version Available

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

Monitor Change Event Publishing and Delivery Usage

To get usage data for event publishing and delivery to CometD and Pub/Sub API clients, empApi Lightning components, and event relays, query the PlatformEventUsageMetric object. Usage data is available for the last 24 hours, ending at the last hour, and for historical daily usage. PlatformEventUsageMetric is available in API version 50.0 and later.

Use PlatformEventUsageMetric to get visibility into your event usage and usage trends. The usage data gives you an idea of how close you are to your allocations and when you need more allocations. The usage metrics stored in PlatformEventUsageMetric are separate from the REST API limits values. Use the REST API limits to track your monthly delivery usage against your allocations. The monthly event delivery usage that the limits API returns is common for platform events and change data capture events in CometD and Pub/Sub API clients, empApi Lightning components, and event relays. PlatformEventUsageMetric breaks down usage of platform events and change data capture events so you can track their usage separately.

Because dates are stored in Coordinated Universal Time (UTC), convert your local dates and times to UTC for the query. For the date format to use, see Date Formats and Date Literals in the SOQL and SOSL Reference.

  • Usage data is stored for at least 45 days. Usage data is updated hourly and is available only when usage is nonzero for a 24-hour period. Usage data isn’t available for 1-hour intervals or any other arbitrary interval. The only supported intervals are the last 24 hours and daily data. Also, usage data isn’t available for standard-volume platform events.
  • After a Salesforce major upgrade, usage data can be inaccurate for the day and the last 24 hours within the upgrade window. New usage data overwrites the data for the hour that the 5-minute upgrade occurs in. The new usage data includes metrics that start after the upgrade for that hour. For more information about Salesforce upgrades, see Salesforce Upgrades and Maintenance in Help and Salesforce Status.

Note

For change events, you can query usage data for these metrics. The first value is the metric name value that you supply in the query.

  • CHANGE_EVENTS_PUBLISHED—Number of change data capture events published
  • CHANGE_EVENTS_DELIVERED—Number of change data capture events delivered to CometD and Pub/Sub API clients, empApi Lightning components, and event relays

For platform events, you can query usage data for these metrics. The first value is the metric name value that you supply in the query.

  • PLATFORM_EVENTS_PUBLISHED—Number of platform events published
  • PLATFORM_EVENTS_DELIVERED—Number of platform events delivered to CometD and Pub/Sub API clients, empApi Lightning components, and event relays

Obtain Usage Metrics for the Last 24 Hours

To get usage metrics for the last 24 hours, ending at the last hour, perform a query by specifying the start and end date and time in UTC, and the metric name.

For the last 24-hour period, the end date is the current date in UTC, with the time rounded down to the previous hour. The start date is 24 hours before the end date. Dates have hourly granularity.

Example

Based on the current date and time of August 4, 2020 11:23 in UTC, the last hour is 11:00. The query includes these dates.

  • Start date in UTC format: 2020-08-03T11:00:00.000Z
  • End date in UTC format: 2020-08-04T11:00:00.000Z

This query returns the usage for the number of platform events delivered between August 3, 2020 at 11:00 and August 4, 2020 at 11:00.

1SELECT Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric 
2WHERE Name='CHANGE_EVENTS_DELIVERED' 
3AND StartDate=2020-08-03T11:00:00.000Z AND EndDate=2020-08-04T11:00:00.000Z

The query returns this result for the last 24-hour usage.

Name StartDate EndDate Value
CHANGE_EVENTS_DELIVERED 2020-08-03T11:00:00.000+0000 2020-08-04T11:00:00.000+0000 575

The time span between StartDate and EndDate is 24 hours for the stored 24-hour usage. Therefore, you can specify either StartDate or EndDate in the query and you get the same result.

Obtain Historical Daily Usage Metrics

To get daily usage metrics for 1 or more days, perform a query by specifying the start date and end date in UTC, and metric name.

Example

To get usage metrics for a period of 3 days, from July 19 to July 22, 2020, use these start and end dates. Time values are 0.

  • Start date for the query: 2020-07-19T00:00:00.000Z
  • End date for the query: 2020-07-22T00:00:00.000Z

This query selects usage metrics for the number of platform events delivered for a 3-day period.

1SELECT Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric 
2WHERE Name='CHANGE_EVENTS_DELIVERED' 
3AND StartDate>=2020-07-19T00:00:00.000Z and EndDate<=2020-07-22T00:00:00.000Z

The query returns these results for the specified date range.

Name StartDate EndDate Value
CHANGE_EVENTS_DELIVERED 2020-07-19T00:00:00.000+0000 2020-07-20T00:00:00.000+0000 575
CHANGE_EVENTS_DELIVERED 2020-07-20T00:00:00.000+0000 2020-07-21T00:00:00.000+0000 899
CHANGE_EVENTS_DELIVERED 2020-07-21T00:00:00.000+0000 2020-07-22T00:00:00.000+0000 1,035

General Considerations

If you query the Id of PlatformEventUsageMetric, the Id value returned isn’t a valid record ID. For example, this query returns an Id field value of 000000000000000AAA.

1SELECT Id, Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric WHERE Name='CHANGE_EVENTS_DELIVERED'

As a result, you can’t use PlatformEventUsageMetric in batch Apex with QueryLocator because QueryLocator requires valid record IDs to be passed in to the execute method. Using PlatformEventUsageMetric with batch Apex and QueryLocator causes unexpected results. Instead, use an iterable with batch Apex and PlatformEventUsageMetric. For more information, see Using Batch Apex in the Platform Events Developer Guide.