Create user session custom metrics for mobile applications

With user session custom metrics (uscm. prefix) , you can extract business-level KPI metrics from your user session data and store them as time series. You can then use the stored metrics in custom charts, alerting mechanisms, or Metrics API.

User session custom metrics can help you answer questions such as:

How is the user experience index for my website 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 mobile app?

You can create and manage user session custom metrics using either the Dynatrace web UI or the Dynatrace Settings API.

Configure metrics via UI

You can create and manage user session custom metrics using the Dynatrace web UI.

From the Dynatrace menu, go to Settings > Web and mobile monitoring > User session custom metrics.
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.
Under Value type to be extracted, select one of the following options:
- 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, which must match the USQL field name. For possible values, see Value field names.
Under Add a dimension, specify fields that should be used as dimensions. Note that dimensions must match the USQL field names. For possible values, see Dimensions.
Under Add a filter, include the required filters.
- Enter the Field name, which must match the USQL field name. For possible values, see Filter field names.
- Select the Operator.
- If you've selected one of the binary operators, for example, equals or greater than, also provide the second argument in the Value text field.

Alternatively, you can use USQL to create user session custom metrics. After you run the entered query, select Create custom metric.

Configure metrics via API

You can also use the Settings API to configure user session custom metrics.

Create an access token with the Write settings (settings.write) and Read settings (settings.read) permissions.

Use the GET a schema endpoint to learn the JSON format required to post your configuration. The metric configuration schema identifier (schemaId) is builtin:custom-metrics. Here is an example JSON payload with the metric configuration:

json
[
 {
     "schemaVersion": "0.0.4",
     "schemaId": "builtin:custom-metrics",
     "scope": "tenant",
     "value": {
         "enabled": true,
         "metricKey": "uscm.session_count_by_browser_family_and_country",
         "value": {
             "type": "COUNTER"
         },
         "dimensions": [
             "browserFamily",
             "country"
         ],
         "filters": [
             {
                 "fieldName": "useraction.application",
                 "operator": "EQUALS",
                 "value": "www.easytravel.com"
             },
             {
                 "fieldName": "userType",
                 "operator": "EQUALS",
                 "value": "REAL_USER"
             }
         ]
     }
 }
 ]

Use the POST an object endpoint to send your configuration.

Configuration properties and supported values

Configuration properties

Property	Description	Possible values
`enabled`	Defines if the custom metric is enabled or not. Set to `false` to temporarily disable the metric.	`true` or `false`
`metricKey`	The metric key used when ingesting the metric. Must start with the `uscm.` prefix. Use this key when requesting the metric data via Data explorer.
`value`	The source of the metric value.
`value.type`	To count the number of user sessions, which is similar to `COUNT(*)` when using USQL, set to `COUNTER`. To extract a value of a user session field, set to `FIELD`. Note that user action fields are not supported.	`COUNTER` or `FIELD`
`value.fieldName`	If `value.type`=`FIELD`, specifies the name of the user session field.	See Value field names.
`dimensions`	Lists the fields used as dimensions.	See Dimensions.
`filters`	Specifies filters.
`filter.fieldName`	Specifies the name of the filter field.	See Filter field names.
`filter.operator`	Specifies the operator.	`EQUALS`, `NOT_EQUAL`, `IS_NULL`, `IS_NOT_NULL`, `LIKE`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`
`filter.value`	For binary operators, for example, `EQUALS` or `GREATER_THAN`, provides the second argument.

Value field names

Dynatrace supports only user session fields. User action fields are not supported.
All field names must match the USQL field names.
The usersession. prefix in the field name is optional. For example, usersession.duration and duration mean the same thing.
When a configured field contains null, the metric is ignored, but Dynatrace uses self-monitoring to identify those cases.

Supported field names

duration
numberOfRageClicks
numberOfRageTaps
totalErrorCount
totalLicenseCreditCount

userActionCount
longProperties.*—Any custom long property, for example, longProperties.outerwidth
doubleProperties.*—Any custom double property, for example, doubleProperties.revenue

Dimensions

Both user session fields and user action fields are supported. User action fields are supported starting with Dynatrace 1.234.
All field names must match the USQL field names.
Prefixes:
- 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 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.

User session fields

appVersion
applicationType
bounce
browserFamily
browserMajorVersion
browserType
carrier
region
continent
country
connectionType
device
displayResolution
endReason
hasCrash
hasError
hasSessionReplay
manufacturer
networkTechnology
newUser
osFamily
osVersion
reasonForNoSessionReplay
reasonForNoSessionReplayMobile
rootedOrJailbroken
screenHeight
screenOrientation
screenWidth
userExperienceScore
userType
stringProperties.*—Any custom string property, for example, stringProperties.author. Use fields with low cardinality to avoid creating too many dimension values.

User action fields

useraction.application (starting with Dynatrace 1.234)

Filter field names

Both user session fields and user action fields are supported.
All field names must match the USQL field names.
Prefixes:
- For a user session field name, the usersession. prefix is optional. For example, usersession.country and country mean the same thing.
- For a user action field name, the useraction. prefix is mandatory.
When you add multiple filters, all of them have to match—filters are combined using AND.
Filters that use a user action field require at least one user action to match. User actions are matched using ANY.
You can set up to 10 filters for a single metric.

User session fields

appVersion
applicationType
bounce
browserFamily
browserMajorVersion
browserMonitorName
browserType
carrier
city
region
continent
country
connectionType
device
displayResolution
duration
endReason
hasCrash
hasError
hasSessionReplay
ip
isp
manufacturer
networkTechnology
newUser
numberOfRageClicks
osFamily
osVersion
reasonForNoSessionReplay
reasonForNoSessionReplayMobile
rootedOrJailbroken
screenHeight
screenOrientation
screenWidth
totalErrorCount
totalLicenseCreditCount
userActionCount
userExperienceScore
userId
userType
longProperties.*—Any custom long property, for example, longProperties.outerwidth
doubleProperties.*—Any custom double property, for example, doubleProperties.revenue
stringProperties.*—Any custom string property, for example, stringProperties.author

User action fields

useraction.apdexCategory
useraction.application
useraction.cdnBusyTime
useraction.cdnResources
useraction.customErrorCount
useraction.domCompleteTime
useraction.domContentLoadedTime
useraction.documentInteractiveTime
useraction.domain
useraction.duration
useraction.firstInputDelay
useraction.firstPartyBusyTime
useraction.firstPartyResources
useraction.frontendTime
useraction.hasCrash
useraction.internalApplicationId
useraction.internalKeyUserActionId
useraction.javascriptErrorCount
useraction.keyUserAction
useraction.largestContentfulPaint
useraction.name
useraction.networkTime
useraction.requestErrorCount
useraction.serverTime
useraction.speedIndex
useraction.targetUrl
useraction.thirdPartyBusyTime
useraction.thirdPartyResources
useraction.type
useraction.visuallyCompleteTime

Known limitations

We've identified the following limitations for user session custom metrics:

You can capture up to 500 custom metrics per environment.
Synthetic user session data is not factored into custom metric values; only real-user data is included.
Dynatrace updates custom metrics each time a session closes. This means that live session data is not factored into 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 custom metric.

Example

To better understand how user session custom metrics work, you can follow the example below.

Using the Dynatrace web UI, let's create an Average session duration metric 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.

Create a metric

From the Dynatrace menu, go to Settings > Web and mobile monitoring > User session custom metrics.
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.

Create and pin a chart

Now let's create a chart based on the uscm.average_duration_of_sessions_by_browser_family_and_version metric and pit this chart to one of your dashboards.

In the Dynatrace menu, go to Data explorer.
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, pin the chart to a dashboard: select Pin to dashboard, select one of your dashboards, and enter the tile name.

Create an alert

As the last part of this example, we'll create an alert based on the user session custom metric.

To create an alert

From the Dynatrace menu, go to Settings > Anomaly detection > Custom events for alerting.
Select Create custom event for alerting.
Create a custom event based on uscm.average_duration_of_sessions_by_browser_family_and_version metric. For details, see Metric events for alerting.

FAQ

I can see the user session data, but I don't see the user session custom metric data in Data explorer.

Make sure the user session is not live. Dynatrace extracts and stores metric data to time series only after a user session is closed.

Why aren't the metrics of live sessions shown in Data explorer?

As sessions are closed in web 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.

Why don't my USQL query results match the custom metric?

Synthetic user session data is not factored into user session custom metrics.

Exclude synthetic sessions from your query. Also, check that the same timeframe is applied to the query and metric.

How are custom metrics from user sessions billed?

Starting with Dynatrace SaaS 1.232, custom metrics from user sessions 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 custom metrics?.

What's the interval granularity for user session custom metrics?

The Dynatrace metric-data persistence follows a data-retention strategy that aggregates metrics over time. The data-retention strategy applied to custom metrics from user sessions is identical to the data-retention strategy used for built-in time series metrics.

For details, see Data retention periods > Metrics