Monitor Platform Event Publishing and Delivery Usage
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 and publishing usage against your allocations. The 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 that 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 and standard 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.
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
For change data capture 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
This table lists which events, publishers, and subscribers are included for each metric.
Metric | Events | Publishers and Subscribers |
---|---|---|
Event publishing metrics: PLATFORM_EVENTS_PUBLISHED and CHANGE_EVENTS_PUBLISHED | All types of events including:
|
All publishing methods including:
|
Event delivery metrics: PLATFORM_EVENTS_DELIVERED and CHANGE_EVENTS_DELIVERED |
|
Subscription methods:
|
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.
SELECT Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric
WHERE Name='PLATFORM_EVENTS_DELIVERED'
AND 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 |
---|---|---|---|
PLATFORM_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. You can specify either StartDate or EndDate in the query and 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 the 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.
SELECT Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric
WHERE Name='PLATFORM_EVENTS_DELIVERED'
AND 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 |
---|---|---|---|
PLATFORM_EVENTS_DELIVERED | 2020-07-19T00:00:00.000+0000 | 2020-07-20T00:00:00.000+0000 | 575 |
PLATFORM_EVENTS_DELIVERED | 2020-07-20T00:00:00.000+0000 | 2020-07-21T00:00:00.000+0000 | 899 |
PLATFORM_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.
SELECT Id, Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric WHERE Name='PLATFORM_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.