With USQL metric events, you can extract business-level KPI metrics from your user session and user action data and store these metrics as time series. You can then use the stored metrics in custom charts, alerting mechanisms, or Metrics API.
USQL metric events are available as:
User session metric events. These metrics are abbreviated as USCMs and have the uscm. prefix.
User action metric events. These metrics are abbreviated as UACMs and start with the uacm. prefix.
User action metric events are available since Dynatrace version 1.260.
USQL metric events can help you answer questions such as:
How is the user experience index for my website changing over time?
How is the Apdex index for a given type of user actions changing over time?
How is the revenue generated by my users changing over time?
How many users are coming to my website and what browsers are they using?
What is the average session duration for my web application?
What is the average user action duration for my mobile application?
You can create and manage USQL metric events using either the Dynatrace web UI or the Dynatrace Settings API.
Configure metrics via UI
You can create and manage USQL metric events using the Dynatrace web UI.
From the Dynatrace menu, go to Settings > Web and mobile monitoring > User session metric events or User action metric events.
Select Add item.
Enter the Metric key that should be used when ingesting the metric. You'll use this key when requesting the metric data via Data explorer.
For user session metric events, start the metric key with the uscm. prefix.
For user action metric events, start the metric key with the uacm. prefix.
Under Value type to be extracted, select one of the following options.
For user session metric events:
User session counter to count the number of user sessions, which is similar to COUNT(*) when using USQL.
User session field value to extract a value of a user session field. Also, specify the Field name. For possible values, see Values for user session metric events.
For user action metric events:
User action counter to count the number of user actions, which is similar to COUNT(*) when using USQL.
User action field value to extract a value of a user action field. Also, specify the Field name. For possible values, see Values for user action metric events.
Both user session and user action fields are supported as dimensions. User action fields are supported starting with Dynatrace version 1.234.
All field names must match the USQL field names.
For a user session field name, the usersession. prefix is optional. For example, usersession.country and country mean the same thing. When ingesting the metric, the usersession. prefix is dropped, for example, usersession.country becomes country.
For a user action field name, the useraction. prefix is mandatory. When ingesting the metric, the useraction. prefix persists.
You can add up to 10 dimensions to a single user session custom metric.
When a field configured as a dimension contains null, Dynatrace uses the null string as a dimension value.
When you use useraction.application as a dimension and a user session spans multiple applications, the value of the user session custom metric is recorded for each application. To avoid the value appearing as double-counted, split the metric by application.
Both user session and user action fields are supported.
All field names must match the USQL field names.
For user action fields, the useraction. prefix is optional. For example, useraction.type and type mean the same thing. When ingesting the metric, the useraction. prefix is dropped, for example, useraction.type becomes type.
For user session fields, the usersession. prefix is required. When ingesting the metric, the usersession. prefix persists.
You can specify up to 4 dimensions for a user action custom metric, but only 2 of them can be high-cardinality dimensions.
When a field configured as a dimension contains null, Dynatrace uses the null string as a dimension value.
In the list below, dimensions in bold are high-cardinality dimensions.
User action fields supported as dimensions
application hasCrash type apdexCategory internalApplicationId internalKeyUserActionId keyUserAction isEntryAction isExitAction stringProperties.*1
1
Any custom string property. Use fields with low cardinality to avoid creating too many dimension values.
Any custom string property, for example, usersession.stringProperties.author. Use fields with low cardinality to avoid creating too many dimension values.
Any custom long, double, or string property, for example, usersession.longProperties.outerwidth, usersession.doubleProperties.revenue, or usersession.stringProperties.author
Known limitations
We've identified the following limitations for USQL metric events:
You can create up to 500 user session custom metrics per environment.
You can create up to 100 user action custom metrics per environment.
Synthetic user session data is not factored into values of USQL metric events; only real-user data is included.
Dynatrace updates USQL metric events each time a session closes. This means that live session data is not factored into USQL custom metric values; only closed session data is included.
The DISTINCT keyword used in USQL is not supported. If you have a query like SELECT COUNT(DISTINCT country) from usersession, it is not possible to create an equivalent USQL custom metric.
Tutorial
To better understand how USQL metric events work, you can follow the tutorial for user session metric events below.
Create a metric
Create and pin a chart
Create an alert
Using the Dynatrace web UI, let's create an Average session duration user session custom metric (USCM) based on the session data of real users. The metric will include two dimensions for segmentation of session data by browser family and major browser version. Using this metric, we will then create a chart for the metric, pin the chart to a dashboard, and create a custom event for the metric so that you can receive alerts when the metric value exceeds a specified threshold.
From the Dynatrace menu, go to Settings > Web and mobile monitoring > User session metric events.
Select Add item.
Enter uscm.average_duration_of_sessions_by_browser_family_and_version as Metric key.
Under Value type to be extracted, select User session field value. Also, set Field name to duration.
Select Add dimension, and add the browserMajorVersion and browserFamily dimensions.
Under Add a filter, include the following filters:
userType = REAL_USER (Field name is userType, Operator is equals, and Value is REAL_USER)
useraction.application = www.easytravel.com (Field name is useraction.application, Operator is equals, and Value is www.easytravel.com). Instead of using the www.easytravel.com value, you can use the name of your own application.
Select Save changes.
Now you have a user session custom metric that is extracted as a field (duration) only when useraction.application equals www.easytravel.com (filtering for a specific application) and userType is REAL_USER (filtering for real users only). Additionally, you have added two dimensions that allow you to split data based on the browser family or major browser version.
Once the user session data is received and the metric is populated, you can chart this metric, pin the chart to a dashboard, and even create an alert based on the metric.
Now let's create a chart based on the uscm.average_duration_of_sessions_by_browser_family_and_version metric and pin this chart to one of your dashboards.
Select the uscm.average_duration_of_sessions_by_browser_family_and_version metric, and select Run query.
Using Data explorer, split the collected data to see the user session data partitioned based on browserMajorVersion, browserFamily, or both.
Filter user session data based on browserMajorVersion or browserFamily to focus on the user session data that interests you.
Once you create a chart presenting your data, you can pin the chart to a classic dashboard: select Pin to dashboard, select one of your dashboards, and enter the tile name.
As sessions are closed in applications, they are pushed to the queue for later processing. A number of background workers then extract metric data from the user sessions to prepare the data for metric ingestion.
Starting with Dynatrace SaaS 1.232, USQL metric events are subject to the Davis data unit (DDU) licensing. These metrics are billed as regular schemaless metrics.
To estimate the cost per metric, the sessions for the last 7 days are evaluated and the cost in DDUs per metric is calculated according to the expected ingestion per minute. For details, see How do we calculate DDU consumption for metric events?.
The Dynatrace metric-data persistence follows a data-retention strategy that aggregates metrics over time. The data-retention strategy applied to USQL metric events is identical to the data-retention strategy used for built-in time series metrics.
