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.

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.

Or add this condition for published events.

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

Or add this condition for change events.

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

• 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.

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.

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.

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