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:
[
{
"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 chartNow 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 alertAs 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