Enhanced Usage Metrics

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.

Before you can get more usage metrics, enable Enhanced Usage Metrics in Metadata API. Set the enableEnhancedUsageMetrics field to true in PlatformEventSettings. See PlatformEventSettings in the Metadata API Developer Guide.

If you don’t specify the StartDate and EndDate in your query, the query returns data for the last 24 hours by default. The example query aggregates the results per event because the EventName field is specified in the SELECT statement. Also, the query aggregates the data per hour as specified by the TimeSegment field. The query also includes the event type and the usage type.

1SELECT EventName, EventType, UsageType, Value, StartDate, EndDate 
2FROM PlatformEventUsageMetric 
3WHERE TimeSegment='Hourly'

In this sample result, usage data for published and delivered events is returned for all events: Order_Event__e and AccountChangeEvent. The query aggregates usage data per hour.

For valid TimeSegment values, check the TimeSegment field of PlatformEventUsageMetric in the Object Reference for the Salesforce Platform.

You can refine the query results by adding fields in the WHERE clause. To view usage data for only a specific usage type, add the UsageType field in the WHERE clause. For example, to query for only delivered event usage, add this condition.

1WHERE UsageType='DELIVERY'

Or add this condition for published events.

1WHERE UsageType='PUBLISH'

You can narrow the query by event type. For example, to query for custom platform events only, add this condition.

1WHERE EventType='CUSTOM_PLATFORM_EVENT'

Or add this condition for change events.

1WHERE UsageType='CHANGE_EVENT'

You can query usage for one event only. For example:

1WHERE EventName='Order_Event__e'

• If StartDate and EndDate aren’t specified in the WHERE clause, the query defaults to the last 24-hour period.
• You must specify the StartDate and EndDate field values in the WHERE clause or neither. If only StartDate or EndDate are specified, you get an error.
• The maximum time span between StartDate and EndDate is 30 days.
• The minimum time span between StartDate and EndDate is 15 minutes.
• The StartDate field can refer to a date that is no more than 60 days old.
• The TimeSegment field must always be specified in the query’s WHERE clause. Optionally, it can also be part of the SELECT statement.
• Make sure that the time span between StartDate and EndDate in the WHERE clause is valid for the TimeSegment value chosen. Check the TimeSegment field of PlatformEventUsageMetric in the Object Reference for the Salesforce Platform.
• A query must have at least one of Name, EventType, or EventName fields in either the SELECT or WHERE clause.
• A query that uses EventName or EventType must also specify the UsageType in either the SELECT or WHERE clause.

• We recommend that you include StartDate and EndDate in the query’s SELECT statement. Including these fields helps you interpret the query results and map each result with its corresponding time segment.
• To make sure the query covers all time segments between the start date and end date, use the >= and <= logical operators with StartDate and EndDate in the WHERE clause. For example: StartDate >= DateTime1 AND EndDate <= DateTime2
• Date fields accept date literals, such as LAST_WEEK, in addition to date values. For more information, see Date Formats and Date Literals in WHERE in the SOQL and SOSL Reference.
• The maximum number of rows that can be returned in a query for enhanced usage metrics is 2,000. If the query generates more than 2,000 rows, you get an error and the query returns no results.
• The LIMIT clause isn’t supported.
• SOQL aggregate functions, such as SUM() and MAX(), aren’t supported. For more information, see Aggregate Functions in the SOQL and SOSL Reference.

The examples in this section follow a scenario that starts with a multiday time range and drills down into smaller time slots to find the time slot with the highest usage. The first example gets daily usage. The second and third examples drill down into hourly and 15-minute usage.

One of the fields these examples use is the Client field. The Client field is populated for both event publish and delivery usages. For publish usages the client can be one of the following: SYSTEM (Change Data Capture events only), PUB_SUB_API, REST_API, FLOW, SOAP_API, BULK_API, or APEX. For delivery usages, the client can be one of the following: PUB_SUB_API, EVENT_RELAY, Streaming API (CometD) client ID, or the Apex Trigger ID starting with 01q. The example query results contain placeholder values for the Client field for simplicity.

This example query gets daily usage metrics for delivered events grouped by event name and client for a period of 2 days. The query aggregates the results per event and client because the EventName and Client fields are specified in the SELECT statement.

1SELECT EventName, EventType, Client, Value, StartDate, EndDate
2FROM PlatformEventUsageMetric
3WHERE TimeSegment='Daily'
4AND UsageType='DELIVERY'
5AND StartDate >= 2023-04-01T00:00:00.000Z  
6AND EndDate <= 2023-04-03T00:00:00.000Z

In this sample result, usage data is returned for all events: Order_Event__e and AccountChangeEvent. The query aggregates usage data by client. Two clients receive Order_Event__e events, and the usage data is computed for each. AccountChangeEvent events are received by one client only.

Query hourly usage to view event usage for delivered events by hour for a time period up to 24 hours. This example query gets usage metrics for one event, Order_Event__e. The query aggregates the results into 1-hour intervals as specified by the TimeSegment field. Results are grouped per event and client because the EventName and Client fields are specified in the SELECT statement.

In the previous daily usage example, April 1 has the highest usage. To drill down into the usage for that day for one event, query for that date.

1SELECT EventName,Client, Value, StartDate, EndDate
2FROM PlatformEventUsageMetric
3WHERE TimeSegment='Hourly'
4AND UsageType='DELIVERY'
5AND EventName='Order_Event__e'
6AND StartDate >= 2023-04-01T00:00:00.000Z  
7AND EndDate <= 2023-04-02T00:00:00.000Z

In this sample result, hourly usage data is returned for Order_Event__e on April 1. The query aggregates usage data by client. Two clients receive Order_Event__e events, and the usage data is computed for each. A partial list of results is included for brevity.

Get event usage aggregated into 15-minute periods for a time period up to 1 hour. This example query gets event delivery usage metrics for one event, Order_Event__e. The query aggregates the results into 15-minute intervals as specified by the TimeSegment field. Results are grouped per event and client because the EventName and Client fields are specified in the SELECT statement.

In the previous hourly usage example, the time period between the hours of 01:00:00 and 02:00:00 on April 1 has the highest usage. To drill down into the usage for that day for one event, query for that date.

1SELECT EventName,Client, Value, StartDate, EndDate
2FROM PlatformEventUsageMetric
3WHERE TimeSegment='FifteenMinutes'
4AND UsageType='DELIVERY'
5AND EventName='Order_Event__e'
6AND client='client1'
7AND StartDate >= 2023-04-01T01:00:00.000Z  
8AND EndDate <= 2023-04-01T02:00:00.000Z

In this sample result, usage data for every 15 minutes is returned for Order_Event__e for client1 on April 1 between the hours of 01:00:00 and 02:00:00.

See Also

• Object Reference for the Salesforce Platform: PlatformEventUsageMetric

j

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

Previous Versions