Platform Events Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
Platform Events Developer Guide
Delivering Custom Notifications with Platform Events
Defining Your Custom Platform Event
Publishing Platform Events
Subscribing to Platform Events
Testing Your Platform Event in Apex
Encrypting Platform Event Messages at Rest in the Event Bus
Monitor Platform Event Publishing and Delivery Usage
Enhanced Usage Metrics
Considerations
Examples
Reference
PDF

Monitor Platform Event Publishing and Delivery Usage

To get usage data for event publishing and delivery to Pub/Sub API and CometD clients, empApi Lightning components, and event relays, query the PlatformEventUsageMetric object. In API 58.0 and later, enable and use Enhanced Usage Metrics to get granular usage data for various time segments. If Enhanced Usage Metrics isn’t enabled, 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.

We recommend that you use Enhanced Usage Metrics. With Enhanced Usage Metrics, you can query usage data at a granular level. You can break down usage metrics by event name, client ID, event type, and usage type. And you can get usage data by various time segments, including daily, hourly, and 15-minute periods. See Enhanced Usage Metrics.

Important

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

Even though usage data is available for the number of change events published through the CHANGE_EVENTS_PUBLISHED metric, no event publishing limit is enforced for change events. Publishing allocations apply only to platform events.

Note

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:
  • Custom platform events
  • Change events
 All publishing methods including:
  • Apex
  • Salesforce APIs including Pub/Sub API
  • Flows
  • Process Builder processes
Event delivery metrics: PLATFORM_EVENTS_DELIVERED and CHANGE_EVENTS_DELIVERED
  • Custom platform events. Delivery metrics don't include Event Monitoring real-time events and standard platform events. .
  • Change events

Subscription methods:

  • CometD, Pub/Sub API, empApi Lightning components, and event relays
  • Delivery metrics don’t include event deliveries to Apex triggers, flows, and processes.

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.