jEncrypting Platform Event Messages at Rest in the Event Bus
Enhanced Usage Metrics
Previous Versions
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.
Instead of completing this task manually, get help from Setup with Agentforce. For example, ask the Setup agent, “What’s my event usage for the past 30 days?” For more information, see Events in Setup with Agentforce.
Tip
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 publishedPLATFORM_EVENTS_DELIVERED—Number of platform events delivered to CometD and Pub/Sub API clients,empApiLightning 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 publishedCHANGE_EVENTS_DELIVERED—Number of change data capture events delivered to CometD and Pub/Sub API clients,empApiLightning 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:
| 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.
1SELECT Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric
2WHERE Name='PLATFORM_EVENTS_DELIVERED'
3AND StartDate=2020-08-03T11:00:00.000Z AND EndDate=2020-08-04T11:00:00.000ZThe 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.
1SELECT Name, StartDate, EndDate, Value FROM PlatformEventUsageMetric
2WHERE Name='PLATFORM_EVENTS_DELIVERED'
3AND StartDate>=2020-07-19T00:00:00.000Z and EndDate<=2020-07-22T00:00:00.000ZThe 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.
1SELECT 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.
-
In API version 58.0 and later, enable Enhanced Usage Metrics to get granular usage data and time segments in PlatformEventUsageMetric queries. You can break down usage metrics by event name, client ID, event type, and usage type. And you can get usage data by granular time segments, including daily, hourly, and 15-minute periods.
See Also
j