Create USQL custom metrics for custom applications

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.

User session metric events page in the Dynatrace web UI

  1. Go to Settings > Web and mobile monitoring > User session metric events or User action metric events.
  2. Select Add item.
  3. 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.
  4. 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.
  5. Under Add a dimension, specify fields that should be used as dimensions. For possible values, see Dimensions for user session metric events and Dimensions for user action metric events.
  6. Under Add a filter, include the required filters.

Creating a user session custom metric

Alternatively, you can use USQL to create USQL metric events.

Configure metrics via API

You can also use the Settings API to configure USQL metric events.

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

  2. Use the GET a schema endpoint to learn the JSON format required to post your configuration.

  3. Use the POST an object endpoint to send your configuration.

The table below explains all configuration properties required to create or update a USQL custom metric via API.

Property

Description

Possible values

enabled

Defines if the USQL 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. Use this key when requesting the metric data via Data Explorer.

  • For user session metric events, the metric key must start with the uscm. prefix.
  • For user action metric events, the metric key must start with the uacm. prefix.

value

The source of the metric value.

value.type

  • To count the number of user sessions or user actions, which is similar to COUNT(*) when using USQL, set to COUNTER.
  • To extract a value of a user session or user action field, set to FIELD.

COUNTER or FIELD

value.fieldName

If value.type=FIELD, specifies the name of the user session or user action field.

dimensions

Lists the fields used as dimensions.

filters

Specifies filters.

filter.fieldName

Specifies the name of the filter field.

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

Provides the second argument for binary operators (such as EQUALS or GREATER_THAN).

Supported values, dimensions, and filters

Check the sections below to view the lists of supported values, dimensions, and filters for user session metric events.

  • Only user session fields are supported as a value. User action fields are not supported as a value.
  • 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.

User session fields supported as values

duration
numberOfRageClicks
numberOfRageTaps
totalErrorCount
totalLicenseCreditCount
userActionCount
longProperties.*1
doubleProperties.*1

1

Any custom long or double property, for example, longProperties.outerwidth or doubleProperties.revenue

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

User session fields supported as dimensions

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.*1

1

Any custom string property, for example, stringProperties.author. Use fields with low cardinality to avoid creating too many dimension values.

User action fields supported as dimensions

useraction.application1

1

Supported starting with Dynatrace version 1.234

  • Both user session and user action fields are supported as filters.
  • 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.
  • 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 user session custom metric.

User session fields supported as filters

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.*1
doubleProperties.*1
stringProperties.*1

1

Any custom long, double, or string property, for example, longProperties.outerwidth, doubleProperties.revenue, or stringProperties.author

User action fields supported as 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

Expand the sections below to explore supported values, dimensions, and filters for user action metric events.

  • Both user session and user action fields are supported as values.
  • 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.
  • For user session fields, the usersession. prefix is required.
  • When a configured field contains null, the metric is ignored, but Dynatrace uses self-monitoring to identify those cases.

User action fields supported as values

speedIndex
duration
networkTime
serverTime
frontendTime
documentInteractiveTime
firstPartyResources
firstPartyBusyTime
thirdPartyResources
thirdPartyBusyTime
cdnResources
cdnBusyTime
domCompleteTime
domContentLoadedTime
loadEventStart
loadEventEnd
visuallyCompleteTime
requestStart
responseStart
responseEnd
userActionPropertyCount
customErrorCount
javascriptErrorCount
requestErrorCount
largestContentfulPaint
firstInputDelay
totalBlockingTime deprecated
cumulativeLayoutShift
longProperties.*1
doubleProperties.*1

1

Any custom long or double property

User session fields supported as values

usersession.duration
usersession.numberOfRageClicks
usersession.numberOfRageTaps
usersession.totalErrorCount
usersession.totalLicenseCreditCount
usersession.userActionCount
usersession.longProperties.*1
usersession.doubleProperties.*1

1

Any custom long or double property, for example, usersession.longProperties.outerwidth or usersession.doubleProperties.revenue

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

User session fields supported as dimensions

usersession.appVersion
usersession.applicationType
usersession.bounce
usersession.browserFamily
usersession.browserMajorVersion
usersession.browserType
usersession.carrier
usersession.region
usersession.continent
usersession.country
usersession.connectionType
usersession.device
usersession.displayResolution
usersession.endReason
usersession.hasCrash
usersession.hasError
usersession.hasSessionReplay
usersession.manufacturer
usersession.networkTechnology
usersession.newUser
usersession.osFamily
usersession.osVersion
usersession.reasonForNoSessionReplay
usersession.reasonForNoSessionReplayMobile
usersession.rootedOrJailbroken
usersession.screenHeight
usersession.screenOrientation
usersession.screenWidth
usersession.userExperienceScore
usersession.userType
usersession.stringProperties.*1

1

Any custom string property, for example, usersession.stringProperties.author. Use fields with low cardinality to avoid creating too many dimension values.

  • Both user session and user action fields are supported as filters.
  • 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.
  • For user session fields, the usersession. prefix is required.
  • When you add multiple filters, all of them have to match—filters are combined using AND.
  • You can set up to 10 filters for a single user action custom metric.

User action fields supported as filters

apdexCategory
application
cdnBusyTime
cdnResources
customErrorCount
cumulativeLayoutShift
domCompleteTime
domContentLoadedTime
documentInteractiveTime
domain
duration
firstInputDelay
firstPartyBusyTime
firstPartyResources
frontendTime
hasCrash
internalApplicationId
internalKeyUserActionId
isEntryAction
isExitAction
javascriptErrorCount
keyUserAction
largestContentfulPaint
loadEventStart
loadEventEnd
name
networkTime
requestErrorCount
requestStart
responseStart
responseEnd
serverTime
speedIndex
targetUrl
thirdPartyBusyTime
thirdPartyResources
totalBlockingTime deprecated
type
userActionPropertyCount
visuallyCompleteTime
syntheticEvent
longProperties.*1
doubleProperties.*1
stringProperties.*1

1

Any custom long, double, or string property

User session fields supported as filters

usersession.appVersion
usersession.applicationType
usersession.bounce
usersession.browserFamily
usersession.browserMajorVersion
usersession.browserMonitorName
usersession.browserType
usersession.carrier
usersession.city
usersession.region
usersession.continent
usersession.country
usersession.connectionType
usersession.device
usersession.displayResolution
usersession.duration
usersession.endReason
usersession.hasCrash
usersession.hasError
usersession.hasSessionReplay
usersession.ip
usersession.isp
usersession.manufacturer
usersession.networkTechnology
usersession.newUser
usersession.numberOfRageClicks
usersession.numberOfRageTaps
usersession.osFamily
usersession.osVersion
usersession.reasonForNoSessionReplay
usersession.reasonForNoSessionReplayMobile
usersession.rootedOrJailbroken
usersession.screenHeight
usersession.screenOrientation
usersession.screenWidth
usersession.totalErrorCount
usersession.totalLicenseCreditCount
usersession.userActionCount
usersession.userExperienceScore
usersession.userId
usersession.userType
usersession.longProperties.*1
usersession.doubleProperties.*1
usersession.stringProperties.*1

1

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.

Step 1

Create a metric

Step 2

Create and pin a chart

Step 3

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.

  1. Go to Settings > Web and mobile monitoring > User session metric events.
  2. Select Add item.
  3. Enter uscm.average_duration_of_sessions_by_browser_family_and_version as Metric key.
  4. Under Value type to be extracted, select User session field value. Also, set Field name to duration.
  5. Select Add dimension, and add the browserMajorVersion and browserFamily dimensions.
  6. 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.
  7. Select Save changes.

Creating a user session custom metric

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.

  1. Go to Data Explorer.

  2. Select the uscm.average_duration_of_sessions_by_browser_family_and_version metric, and select Run query.

    Creating a chart in Data Explorer based on user sessions metric

  3. Using Data Explorer, split the collected data to see the user session data partitioned based on browserMajorVersion, browserFamily, or both.

  4. Filter user session data based on browserMajorVersion or browserFamily to focus on the user session data that interests you.

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

Custom metric chart pinned to the dashboard

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

To create an alert

  1. Go to Settings > Anomaly detection > Metric events.
  2. Select Add metric event.
  3. Create a metric event based on uscm.average_duration_of_sessions_by_browser_family_and_version metric. For details, see Metric events.

Creating a custom event for alerting based on a user sessions metric

Frequently asked questions

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

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.

Synthetic user session data is not factored into USQL metric events.

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

Starting with Dynatrace 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.

For details, see Data retention periods > Metrics

Related topics