User sessions API - User session structure

This page provides descriptions of all possible fields that a user session might include.

Be aware that with Dynatrace version 1.204, we’ve introduced new error counts in USQL and Session export for every user action, which are fully consistent across Dynatrace. In turn, we'll deprecate the following error counts with Dynatrace version 1.217:

  • useraction.errorCount — Only includes JavaScript errors.
  • useraction.httpRequestsWithErrors — Only considers server-side errors.
  • useraction.failedXHRRequests — Only considers failed XHR calls made in your end user's browser.
  • useraction.failedImages — Will be included with the new requestErrorCount.

Read more about how to best replace existing error counts with the new ones.

The UserSession object

A user session, encompassing multiple user actions and additional information about a user's visit.

Element Type Description Required
tenantId string

The ID of the Dynatrace environment that captured the user session.

This field can not be queried via the User Session Query Language.

optional
userSessionId string

The unique ID of the user session.

optional
startTime integer

The timestamp of the first user action in the user session, in UTC milliseconds.

optional
endTime integer

The timestamp of the last user action in the user session, in UTC milliseconds.

optional
duration integer

The duration of the user session, in milliseconds.

This is calculated as the amount of time between the start of the first user action and the end of the last user action.

optional
internalUserId string

The unique ID of the user that triggered the user session.

optional
userType string

The type of the user. Indicates either a real human user (REAL_USER) or a robot (ROBOT or SYNTHETIC).

optional
reasonForNoSessionReplay string

The reason for absence of Session Replay.

optional
reasonForNoSessionReplayMobile string

The reason for absence of Session Replay on mobile.

optional
applicationType string

The type of the application used in the user session.

optional
bounce boolean

The user session has (true) or doesn't have (false) a bounce.

A bounce means there is only one user action in the user session.

optional
newUser boolean

The user is a first-time (true) or a returning user (false).

optional
userActionCount integer

The number of user actions in the user session.

optional
totalErrorCount integer

The number of errors detected in the user session.

optional
totalLicenseCreditCount integer

The amount of DEM units consumed by the session.

optional
matchingConversionGoalsCount integer

The number of conversion goals achieved by the user session.

optional
matchingConversionGoals string[]

A list of conversion goals achieved by the user session.

Additionally, you can define conversion goals for a single user action.

optional
ip string

The IP address (IPv4 or IPv6) from which the user session originates.

optional
continent string

The continent from which the user session originates (based on the IP address).

optional
country string

The country from which the user session originates (based on the IP address).

optional
region string

The region from which the user session originates (based on the IP address).

optional
city string

The city from which the user session originates (based on the IP address).

optional
browserType string

The type of browser used for the user session.

optional
browserFamily string

The family of the browser used for the user session.

optional
browserMajorVersion string

The version of the browser used for the user session.

optional
osFamily string

The type of operating system used for the user session.

optional
osVersion string

The version of the operating system used for the user session.

optional
manufacturer string

The detected manufacturer of the device used for the user session.

optional
device string

The detected device used for the user session.

optional
userId string

The user ID provided for the user session by session tagging.

optional
screenHeight integer

The detected screen height of the device used for the user session.

optional
screenWidth integer

The detected screen width of the device used for the user session.

optional
screenOrientation string

The detected screen orientation of the device used on the device for the user session.

optional
displayResolution string

The detected screen resolution of the device used for the user session.

optional
hasCrash boolean

The user session includes (true) or doesn't include (false) a crash.

optional
crashGroupId string

If a mobile session crashed, this is the ID of the group to which the crashed session belongs.

If the session did not crash or the session is not a mobile session, it has the null value.

optional
hasSessionReplay boolean

Session Replay is (true) or is not (false) available for the session.

optional
isp string

The internet service provider from which the user session originates (based on the IP address).

optional
clientType string

Additional information about the client.

This field can not be queried via the user session query language. Use the browserType field instead.

optional
browserMonitorId string

The ID of the Synthetic browser monitor that created the session.

optional
browserMonitorName string

The name of the Synthetic browser monitor that created the session.

optional
stringProperties StringProperty[]

A list of custom properties of the user session with string values.

optional
longProperties LongProperty[]

A list of custom properties of the user session with integer (short or long) values.

optional
doubleProperties DoubleProperty[]

A list of custom properties of the user session with floating-point numerical values.

optional
dateProperties DateProperty[]

A list of custom properties of the user session with date values.

optional
userActions UserSessionUserAction[]

A list of user actions recorded in the user session.

optional
events UserSessionEvents[]

A list of additional events recorded in the user session.

optional
errors UserSessionErrors[]

A list of errors recorded in the user session.

optional
syntheticEvents UserSessionSyntheticEvent[]

A list of synthetic events recorded in the user session.

optional
appVersion string

The version of the application where the user session has been recorded.

This information is provided by another integration, such as OpenKit.

optional
endReason string

The reason for the end of the user session.

optional
numberOfRageClicks integer

The number of rage clicks detected in the user session.

optional
userExperienceScore string

The user experience score of the user session.

optional
carrier string

The carrier information of the mobile user session.

optional
networkTechnology string

The network technology information of the mobile user session.

optional
connectionType string

The serialized connection type of the mobile user session.

optional
replayStart integer

The timestamp of the Session Replay start, in UTC milliseconds.

optional
replayEnd integer

The timestamp of the Session Replay end, in UTC milliseconds.

optional
clientTimeOffset integer

The time offset of the client, in milliseconds

optional
rootedOrJailbroken boolean

The mobile device is rooted/jailbroken (true) or genuine (false).

Has the value of null if the status is unknown or undefined. Custom applications always report unknown/undefined.

optional
hasError boolean

The user session includes (true) or doesn't include (false) an error.

optional

The UserSessionSyntheticEvent object

A synthetic event of a user session.

Element Type Description Required
name string

The name of the synthetic event.

optional
syntheticEventId string

The Dynatrace entity ID for the synthetic event.

optional
sequenceNumber integer

The sequence number of the synthetic event in scope of the complete browser monitor.

optional
timestamp integer

The timestamp when the synthetic event was simulated, in UTC milliseconds.

optional
type string

The type of the synthetic event. For example click or keystroke.

optional
errorCode integer

The error code of the error that occurred during this event.

optional
errorName string

Description of the error that occurred during this event.

optional

The UserSessionErrors object

The error of a user session.

Element Type Description Required
type string

The type of error.

optional
name string

The name of the error.

optional
domain string

The DNS domain where the error has been recorded.

optional
startTime integer

The timestamp of the error, in UTC milliseconds.

optional
application string

The name of the application, based on the configured detection rules.

optional
internalApplicationId string

The Dynatrace entity ID of the application.

This information is useful when calling various REST APIs, for example, as a key for time series queries.

optional

The UserSessionEvents object

The external event of a user session.

Element Type Description Required
type string

The type of event.

optional
name string

The name of the event.

optional
domain string

The DNS domain where the event has been recorded.

optional
startTime integer

The timestamp of the event, in UTC milliseconds.

optional
application string

The name of the application, based on the configured detection rules.

optional
internalApplicationId string

The Dynatrace entity ID of the application.

This information is useful when calling various REST APIs, for example, as a key for time series queries.

optional
metadata string

The metadata attached to the event.

optional
page string

The name of the page the user navigated to during a page change event.

optional
pageGroup string

The page group is automatically derived from the page.

optional
pageReferrer string

The name of the previous page from which the user navigated from during a page change event.

optional
pageReferrerGroup string

The page referrer group is automatically derived from the page referrer.

optional

The UserSessionUserAction object

A user action.

A user action is a single action performed by the user as part of a user session, for example a mouse click.

Element Type Description Required
name string

The name of the user action.

Typically, this is the name of the page that is loaded as part of a user action or a textual description of the action, such as a mouse click.

optional
domain string

The DNS domain where the user action has been recorded.

optional
targetUrl string

The target URL of the user action.

optional
type string

The type of the user action.

optional
startTime integer

The start timestamp of the user action, in UTC milliseconds.

optional
endTime integer

The end timestamp of the user action, in UTC milliseconds.

optional
duration integer

The duration of the user action, in milliseconds.

This is calculated as the of time between the start and the end timestamps of the user action.

optional
application string

The name of the application where the user action has been recorded.

optional
internalApplicationId string

The Dynatrace entity ID of the application where the user action has been recorded.

This information is useful when calling various REST APIs, for example as a key for time series queries.

optional
internalKeyUserActionId string

The Dynatrace entity ID of the key user action.

optional
speedIndex integer

The speed index of the user action, in milliseconds.

This is calculated as average time it takes for all visible parts of a page to display.

optional
apdexCategory string

The user experience index of the user action.

optional
matchingConversionGoals string[]

A list of conversion goals achieved by the user action.

Additionally, you can define conversion goals for a user session as a whole.

optional
networkTime integer

The amount of time spent on the data transfer for the user action, in milliseconds.

optional
serverTime integer

The amount of time spent on the server-side processing for the user action, in milliseconds.

optional
frontendTime integer

The amount of time spent on the frontend rendering for the user action, in milliseconds.

optional
documentInteractiveTime integer

The amount of time spent until the document for the user action became interactive, in milliseconds.

optional
thirdPartyResources integer

The number of third party resources loaded for the user action.

optional
thirdPartyBusyTime integer

The time spent waiting for third party resources for the user action, in milliseconds.

optional
cdnResources integer

The number of resources fetched from a CDN for the user action.

optional
cdnBusyTime integer

The time spent waiting for CDN resources for the user action, in milliseconds.

optional
firstPartyResources integer

The number of resources fetched from the originating server for the user action.

optional
firstPartyBusyTime integer

The time spent waiting for resources from the originating server for the user action, in milliseconds.

optional
hasCrash boolean

The user action has (true) or doesn't have (false) a crash.

optional
domCompleteTime integer

The amount of time until the DOM tree is completed, in milliseconds.

optional
domContentLoadedTime integer

The amount of time until the DOM tree is loaded, in milliseconds.

optional
loadEventStart integer

The amount of time until the load event started, in milliseconds.

optional
loadEventEnd integer

The amount of time until the load event ended, in milliseconds.

optional
navigationStart integer

The timestamp of the navigation start, in UTC milliseconds.

optional
requestStart integer

The amount of time until the request started, in milliseconds.

optional
responseStart integer

The amount of time until the response started, in milliseconds.

optional
responseEnd integer

The amount of time until the response ended, in milliseconds.

optional
visuallyCompleteTime integer

The amount of time until the page is visually complete, in milliseconds.

optional
syntheticEvent string

The name of the Synthetic event that triggered the user action.

optional
syntheticEventId string

The ID of the Synthetic event that triggered the user action.

optional
keyUserAction boolean

The action is (true) or is not (false) a key action.

optional
stringProperties StringProperty[]

A list of custom properties of the user session with string values.

optional
longProperties LongProperty[]

A list of custom properties of the user session with integer (short or long) values.

optional
doubleProperties DoubleProperty[]

A list of custom properties of the user session with floating-point numerical values.

optional
dateProperties DateProperty[]

A list of custom properties of the user session with date values.

optional
userActionPropertyCount integer

The total number of properties in the user action.

optional
customErrorCount integer

The total number of custom errors during the user action.

optional
javascriptErrorCount integer

The total number of Javascript errors during the user action.

optional
requestErrorCount integer

The total number of request errors during the user action.

optional
largestContentfulPaint integer

The largest contentful paint (LCP) is the time (in milliseconds) that the largest element on the page took to render.

The LCP is an important user-centric metric for measuring load speed. It marks the point when the page's main content is likely loaded. A low LCP indicates that the page loads quickly.

optional
firstInputDelay integer

The first input delay (FID) is the time (in milliseconds) that the browser took to respond to the first user input.

The FID is an important user-centric metric for measuring load responsiveness. It quantifies the user experience when trying to interact with unresponsive pages. A low FID indicates that the page is usable.

optional
totalBlockingTime integer

The total blocking time is the total time (in milliseconds) between the first contentful paint and the time to interactive, during which the browser has been blocked long enough to prevent input responsiveness.

optional
cumulativeLayoutShift number

The cumulative layout shift (CLS) is the total amount of all individual scores for every unexpected layout shift that occurs during the entire lifespan of the page.

The CLS is an important user-centric metric for measuring visual stability. It quantifies how often users experience unexpected layout shifts. A low CLS indicates that the page is delightful.

optional

The DateProperty object

A custom property of the user-action with a date value.

Element Type Description Required
key string

The custom key of the property.

optional
value string

The date value of the property.

optional

The DoubleProperty object

A custom property of the user action with a Double value.

Element Type Description Required
key string

The custom key of the property.

optional
value number

The floating-point numeric value of the property.

optional

The LongProperty object

A custom property of the user action with a Long value.

Element Type Description Required
key string

The custom key of the property.

optional
value integer

The Long value of the property.

optional

The StringProperty object

A custom property of the user action with a string value.

Element Type Description Required
key string

The custom key of the property.

optional
value string

The string value of the property.

optional