• Home
  • How to use Dynatrace
  • RUM
  • Setup and configuration
  • Web applications
  • Additional configuration
  • Configure user session exports

Configure user session exports

Dynatrace can continually send user session data to a provided webhook endpoint. The server that provides the webhook needs to listen for PUT or POST requests on a URL specified as part of the configuration.

The data for completed user sessions is sent in bulk to improve performance, with a flush every few seconds to export the data as soon as the user session is marked as complete.

To configure user session exports, go to Settings > Integration > User session exports. See below for details.

1. Define your endpoints

Endpoint setup

You can configure up to three HTTPS endpoints. Finished user sessions are sent in bulk to all defined endpoints.

For security reasons, Dynatrace only allows HTTPS endpoints.

If you aren't using an Elasticsearch installation as destination, the data is sent to an endpoint via a PUT call with a bulk JSON payload.

  • Operation: PUT (or POST if configured).
  • Path: <as configured>.
  • MIME type: application/json by default, but sent as multiple JSON documents in bulk line-by-line.

    When sending to Elasticsearch, set the MIME type to application/x-ndjson.

  • Response body: The handler should respond with HTTP 200 "OK".
  • Description: Dynatrace sends user sessions in bulk as soon as one of the following conditions is met:
    • 1000 user sessions have finished
    • The bulk size exceeds 896,000 bytes
    • No user session has finished in the last 30 seconds

    To prevent system overload, Dynatrace cancels the request when your endpoint doesn't respond within 30 seconds. Dynatrace retries three more times before it finally discards the request and sends an alert notification with the Request timeout error message.

Sample code when using the Jersey REST framework

The following sample code uses the open source Jersey REST framework to provide the necessary endpoint for receiving the data.

java
@Path("/export/") public class ExportREST { ... @PUT @Produces(MediaType.APPLICATION_JSON) @Path("events") public JResponse<String> jsonEvents(final String data) { ... // split the bulk into single documents final String[] lines = StringUtils.split(data, '\n'); for(String line : lines) { ... // handle the JSON-data } return JResponse.ok("") .header(HttpHeaders.SERVER, "Endpoint for Dynatrace session data export") .build(); } }

2. Configure basic authentication

Basic authentication enables you to secure your endpoints.

To configure user session export for basic authentication

  1. On the User session exports page, under Authentication, turn on Activate.
  2. Select Basic authentication
  3. Enter your username and password.

The password is encrypted and masked in your environment.

You'll need to re-enter the basic authentication password when testing your configuration.

3. Send data directly to Elasticsearch

To send data directly to your Elasticsearch installation

  1. Make sure your Elasticsearch instance is reachable from the cluster server. For Dynatrace SaaS deployments, this means it needs to be publicly available. You can use an SSL certificate and basic authentication to secure access.
  2. Make sure your export URL has the following format: https://<your_host>:9200/_bulk. Replace <your_host> with your actual value.
  3. On the User session exports page, under Send data directly to Elasticsearch section, turn on Activate.
  4. Enter the name of the index where data is sent and the type of documents in the Elasticsearch index.

Elasticsearch index

Create an index where you want to send data and define the mapping for your index. See Download a sample mapping for details on how to download a sample mapping for your configuration.

If you don't create the index before enabling user session export, your Elasticsearch installation automatically creates the mappings for the fields. This automatic mapping doesn't create the appropriate field mappings in all cases. For example, date fields are mapped as long.

Elasticsearch index type

Elasticsearch is currently removing support for mapping types. The way you create indexes and configure types depends on your Elasticsearch version. See below for details.

We recommend that you set _doc as the type of document regardless of the Elasticsearch version you're running.

  • Elasticsearch version 6
    • You can specify one single type per index.
    • When creating an index, you can specify an include_type_name query string parameter to indicate that requests and responses should include a type name. This parameter defaults to true. If you don't set it, you get a deprecation warning. If you don't specify any type when creating an index, _doc is used.
  • Elasticsearch version 7
    • Specifying types is deprecated in this Elasticsearch version. The include_type_name parameter defaults to false now.
    • You can force Elasticsearch to use a type name by setting the parameter to true, which results in a deprecation warning.
  • Elasticsearch version 8
    • Specifying types is no longer supported. Starting with this version, you are required to use _doc as the document type. For more information, see Removal of mapping types.

Type refers to the "index type" used in Elasticsearch and doesn't restrict which user sessions are exported. Regardless of the type you choose to configure, all user session data—including user actions, events, and errors—is exported.

To restrict the user sessions you export, you can define a management zone. See Export scope for details.

4. Export scope

You can define the scope of your export by selecting a management zone in the Export scope, alerting, and advanced configuration section.

After selecting a management zone, only user sessions that have at least one user action with a matching application are included in the export.

Restricting the export to synthetic only user sessions isn't currently possible.

Advanced configuration

You can configure additional details of your user-session export under Export scope, alerting, and advanced configuration.

  • You can turn on Disable notification if you don't want to receive notifications when your user session export fails.
  • You can specify Custom configuration properties to further tweak the export configuration. Contact Dynatrace support before changing this field.
  • If you experience any issues with user session export, contact Dynatrace support before entering any additional properties.

5. Test export

To test your configuration, select Test export. Dynatrace uses the current configuration to perform a user session export of up to 50 documents from the last seven days. If no data is available during this timeframe, the test export isn't available. As soon as the test export finishes, you are notified of the results.

  • You don't need to save a configuration to test your endpoint.
  • If you set up an endpoint that is secured via basic authentication, you need to test your configuration before saving it.
  • You need to re-enter your basic authentication password when testing your configuration.

6. Download a sample dataset

To see what data export will look like when you export it to your endpoints, select Download sample export data.

  • The sample dataset consists of up to 50 user sessions tracked in your environment for the last seven days. If there aren't any user sessions during this timeframe, downloading sample data isn't available.
  • If you configured a regular endpoint for your user session export, the sample data will contain user sessions in JSON format, separated by newline characters.
Sample: three sessions sent in bulk as three lines
plaintext
{"tenantId":"umsaywsjuo","userSessionId":"1394_1008","startTime":1511441593539,"endTime":1511441716896,"duration":123357,"internalUserId":"1394","userType":"REAL_USER","applicationType":"MOBILE_APPLICATION","bounce":false,"newUser":false,"userActionCount":1,"totalErrorCount":1,"ip":"2001:1800:ffff:eac2:63f5:568e:b3c6:6c54","geolocationContinentName":"North America","geolocationCountryName":"United States","geolocationRegionName":"Florida","geolocationCityName":"Delray Beach","osFamilyName":"Windows","osVersionName":"Windows 10.0 Mobile","manufacturer":"Nokia","device":"L-930","userId":"fearghasbag","screenHeight":1920,"screenWidth":1080,"screenOrientation":"PORTRAIT","displayResolution":"FHD","hasCrash":true,"isp":"SWCP-AS - Southwest Cyberport","stringTags":{ },"numTags":{ },"dateTags":{ },"userActions":[ { "name":"Checkout","type":"Custom","startTime":1511441593539,"endTime":1511441593562,"duration":23,"application":"easyTravel Demo","speedIndex":null,"errorCount":0,"apdexCategory":"UNKNOWN","networkTime":null,"serverTime":null,"frontendTime":null,"documentInteractiveTime":null,"failedImages":null,"failedXhrRequests":null,"httpRequestsWithErrors":null,"thirdPartyResources":null,"thirdPartyBusyTime":0,"cdnResources":null,"cdnBusyTime":0,"firstPartyResources":null,"firstPartyBusyTime":0,"hasCrash":false,"domCompleteTime":null,"domContentLoadedTime":null,"loadEventStart":null,"loadEventEnd":null,"navigationStart":null,"requestStart":null,"responseStart":null,"responseEnd":null,"visuallyCompleteTime":null } ],"events":[ { "type":"UserTag","name":"fearghasbag","startTime":1511441593562,"application":"MOBILE_APPLICATION-752C288D59734C79" } ],"errors":[ { "type":"Crash","name":"ThrowAsync","startTime":1511441716896,"application":"MOBILE_APPLICATION-752C288D59734C79"}]} {"tenantId":"umsaywsjuo","userSessionId":"1394_1008","startTime":1511441593539,"endTime":1511441716896,"duration":123357,"internalUserId":"1394","userType":"REAL_USER","applicationType":"MOBILE_APPLICATION","bounce":false,"newUser":false,"userActionCount":1,"totalErrorCount":1,"ip":"2001:1800:ffff:eac2:63f5:568e:b3c6:6c54","geolocationContinentName":"North America","geolocationCountryName":"United States","geolocationRegionName":"Florida","geolocationCityName":"Delray Beach","osFamilyName":"Windows","osVersionName":"Windows 10.0 Mobile","manufacturer":"Nokia","device":"L-930","userId":"fearghasbag","screenHeight":1920,"screenWidth":1080,"screenOrientation":"PORTRAIT","displayResolution":"FHD","hasCrash":true,"isp":"SWCP-AS - Southwest Cyberport","stringTags":{ },"numTags":{ },"dateTags":{ },"userActions":[ { "name":"Checkout","type":"Custom","startTime":1511441593539,"endTime":1511441593562,"duration":23,"application":"easyTravel Demo","speedIndex":null,"errorCount":0,"apdexCategory":"UNKNOWN","networkTime":null,"serverTime":null,"frontendTime":null,"documentInteractiveTime":null,"failedImages":null,"failedXhrRequests":null,"httpRequestsWithErrors":null,"thirdPartyResources":null,"thirdPartyBusyTime":0,"cdnResources":null,"cdnBusyTime":0,"firstPartyResources":null,"firstPartyBusyTime":0,"hasCrash":false,"domCompleteTime":null,"domContentLoadedTime":null,"loadEventStart":null,"loadEventEnd":null,"navigationStart":null,"requestStart":null,"responseStart":null,"responseEnd":null,"visuallyCompleteTime":null } ],"events":[ { "type":"UserTag","name":"fearghasbag","startTime":1511441593562,"application":"MOBILE_APPLICATION-752C288D59734C79" } ],"errors":[ { "type":"Crash","name":"ThrowAsync","startTime":1511441716896,"application":"MOBILE_APPLICATION-752C288D59734C79"}]} {"tenantId":"umsaywsjuo","userSessionId":"1394_1008","startTime":1511441593539,"endTime":1511441716896,"duration":123357,"internalUserId":"1394","userType":"REAL_USER","applicationType":"MOBILE_APPLICATION","bounce":false,"newUser":false,"userActionCount":1,"totalErrorCount":1,"ip":"2001:1800:ffff:eac2:63f5:568e:b3c6:6c54","geolocationContinentName":"North America","geolocationCountryName":"United States","geolocationRegionName":"Florida","geolocationCityName":"Delray Beach","osFamilyName":"Windows","osVersionName":"Windows 10.0 Mobile","manufacturer":"Nokia","device":"L-930","userId":"fearghasbag","screenHeight":1920,"screenWidth":1080,"screenOrientation":"PORTRAIT","displayResolution":"FHD","hasCrash":true,"isp":"SWCP-AS - Southwest Cyberport","stringTags":{ },"numTags":{ },"dateTags":{ },"userActions":[ { "name":"Checkout","type":"Custom","startTime":1511441593539,"endTime":1511441593562,"duration":23,"application":"easyTravel Demo","speedIndex":null,"errorCount":0,"apdexCategory":"UNKNOWN","networkTime":null,"serverTime":null,"frontendTime":null,"documentInteractiveTime":null,"failedImages":null,"failedXhrRequests":null,"httpRequestsWithErrors":null,"thirdPartyResources":null,"thirdPartyBusyTime":0,"cdnResources":null,"cdnBusyTime":0,"firstPartyResources":null,"firstPartyBusyTime":0,"hasCrash":false,"domCompleteTime":null,"domContentLoadedTime":null,"loadEventStart":null,"loadEventEnd":null,"navigationStart":null,"requestStart":null,"responseStart":null,"responseEnd":null,"visuallyCompleteTime":null } ],"events":[ { "type":"UserTag","name":"fearghasbag","startTime":1511441593562,"application":"MOBILE_APPLICATION-752C288D59734C79" } ],"errors":[ { "type":"Crash","name":"ThrowAsync","startTime":1511441716896,"application":"MOBILE_APPLICATION-752C288D59734C79"}]}

If you configured your endpoint to send data directly to Elasticsearch, the sample data also contains header lines as shown in the example below. These are used to tell Elasticsearch what to do with the data.

Sample: a session sent to Elasticsearch
plaintext
{ "index" : { "_index" : "my-index", "_type" : "_doc", "_id" : "umsaywsjuo-744377345-1622107543233" } } {"tenantId":"umsaywsjuo","userSessionId":"744377345","startTime":1622107543233,"endTime":1622107578205,"duration":34972,"internalUserId":"744377345","userType":"SYNTHETIC","applicationType":"WEB_APPLICATION","bounce":false,"newUser":true,"userActionCount":12,"totalErrorCount":5,"totalLicenseCreditCount":0,"matchingConversionGoalsCount":0,"ip":"157.25.19.100","continent":"Europe","country":"Poland","region":"synthetic","city":"Bydgoszcz","browserType":"Synthetic Agent","browserFamily":"Synthetic monitor","browserMajorVersion":"Synthetic monitor","osFamily":"Linux","osVersion":"Linux","screenHeight":1080,"screenWidth":1920,"screenOrientation":"LANDSCAPE","displayResolution":"FHD","hasSessionReplay":false,"isp":"T-Mobile Czech Republic","clientType":"Synthetic Agent","browserMonitorId":"SYNTHETIC_TEST-18B209EFE2F438F8","browserMonitorName":"mySampleEnv.dynatrace.com - browser monitor - analysis","stringProperties":[],"longProperties":[],"doubleProperties":[],"dateProperties":[],"userActions":[{"name":"/rest/cvalidation/validate/%2fvalidateappmetrickey?input=<masked>&appmetrickey=<masked>&gtf=<masked>","domain":"mySampleEnv.dynatrace.com","targetUrl":"https://mySampleEnv.dynatrace.com/#monitoranalysiskpm;webcheckId=SYNTHETIC_TEST-67444FBB89C6F11B;actionType=Load;splitting=event;analysisTf=custom1622103968000to1622107568000;mode=performance;analysisActionType=Load;gtf=l_2_HOURS","type":"Xhr","startTime":1622107568648,"endTime":1622107569320,"duration":672,"application":"mySampleEnv.dynatrace.com - browser monitor - analysis - 1620645163422","internalApplicationId":"APPLICATION-A8894472DACEDA0E","speedIndex":null,"apdexCategory":"FRUSTRATED","matchingConversionGoals":[],"networkTime":5,"serverTime":58,"frontendTime":609,"documentInteractiveTime":null,"thirdPartyResources":1,"thirdPartyBusyTime":659,"cdnResources":0,"cdnBusyTime":null,"firstPartyResources":9,"firstPartyBusyTime":333,"domCompleteTime":null,"domContentLoadedTime":null,"loadEventStart":null,"loadEventEnd":null,"navigationStart":1622107568730,"requestStart":2,"responseStart":60,"responseEnd":63,"visuallyCompleteTime":null,"syntheticEvent":"click on \"Analyze performance\"","syntheticEventId":"SYNTHETIC_TEST_STEP-7D9201BEB990247E","keyUserAction":false,"stringProperties":[],"longProperties":[],"doubleProperties":[],"dateProperties":[],"userActionPropertyCount":0,"customErrorCount":0,"javascriptErrorCount":0,"requestErrorCount":1,"largestContentfulPaint":null,"firstInputDelay":null,"totalBlockingTime":null,"cumulativeLayoutShift":null},{"name":"/rest/webcheckdetails/overviewdata/browsermonitoranalysis/synthetic_<masked>?selectedtimeframe=<masked>&actiontype=<masked>&analysistf=<masked>&analysismode=<masked>&analysisoverviewsplitting=<masked>&analysisactiontype=<masked>&parts_details=<masked>&parts_chart=<masked>&parts=<masked>&timeframe=<m","domain":"mySampleEnv.dynatrace.com","targetUrl":"https://mySampleEnv.dynatrace.com/#monitoranalysiskpm;webcheckId=SYNTHETIC_TEST-67444FBB89C6F11B;actionType=Load;splitting=event;analysisTf=custom1622103968000to1622107568000;mode=performance;analysisActionType=Load;gtf=l_2_HOURS","type":"Xhr","startTime":1622107569821,"endTime":1622107570083,"duration":262,"application":"mySampleEnv.dynatrace.com - browser monitor - analysis - 1620645163422","internalApplicationId":"APPLICATION-A8894472DACEDA0E","speedIndex":null,"apdexCategory":"FRUSTRATED","matchingConversionGoals":[],"networkTime":5,"serverTime":65,"frontendTime":192,"documentInteractiveTime":null,"thirdPartyResources":0,"thirdPartyBusyTime":null,"cdnResources":0,"cdnBusyTime":null,"firstPartyResources":5,"firstPartyBusyTime":223,"domCompleteTime":null,"domContentLoadedTime":null,"loadEventStart":null,"loadEventEnd":null,"navigationStart":1622107569826,"requestStart":3,"responseStart":68,"responseEnd":70,"visuallyCompleteTime":null,"syntheticEvent":"click on \"Analyze performance\"","syntheticEventId":"SYNTHETIC_TEST_STEP-7D9201BEB990247E","keyUserAction":false,"stringProperties":[],"longProperties":[],"doubleProperties":[],"dateProperties":[],"userActionPropertyCount":0,"customErrorCount":0,"javascriptErrorCount":0,"requestErrorCount":1,"largestContentfulPaint":null,"firstInputDelay":null,"totalBlockingTime":null,"cumulativeLayoutShift":null},{"name":"/rest/webcheckdetails/overviewdata/browsermonitoranalysis/synthetic_<masked>?selectedtimeframe=<masked>&actiontype=<masked>&analysistf=<masked>&analysismode=<masked>&analysisoverviewsplitting=<masked>&visitid=<masked>&timestamp=<masked>&analysisactiontype=<masked>&parts=<masked>&timeframe=<masked>&g","domain":"mySampleEnv.dynatrace.com","targetUrl":"https://mySampleEnv.dynatrace.com/#monitoranalysiskpm;webcheckId=SYNTHETIC_TEST-67444FBB89C6F11B;actionType=Load;splitting=event;analysisTf=custom1622103968000to1622107568000;ensureAnalysisTimeframe=true;mode=performance;visitId=623513409;analysisActionType=Load;gtf=l_2_HOURS","type":"Xhr","startTime":1622107572811,"endTime":1622107572911,"duration":100,"application":"mySampleEnv.dynatrace.com - browser monitor - analysis - 1620645163422","internalApplicationId":"APPLICATION-A8894472DACEDA0E","speedIndex":null,"apdexCategory":"SATISFIED","matchingConversionGoals":[],"networkTime":14,"serverTime":61,"frontendTime":25,"documentInteractiveTime":null,"thirdPartyResources":0,"thirdPartyBusyTime":null,"cdnResources":0,"cdnBusyTime":null,"firstPartyResources":2,"firstPartyBusyTime":167,"domCompleteTime":null,"domContentLoadedTime":null,"loadEventStart":null,"loadEventEnd":null,"navigationStart":1622107572831,"requestStart":12,"responseStart":73,"responseEnd":75,"visuallyCompleteTime":null,"syntheticEvent":"open first execution","syntheticEventId":"SYNTHETIC_TEST_STEP-3A281F8FB8AB3C37","keyUserAction":false,"stringProperties":[],"longProperties":[],"doubleProperties":[],"dateProperties":[],"userActionPropertyCount":0,"customErrorCount":0,"javascriptErrorCount":0,"requestErrorCount":0,"largestContentfulPaint":null,"firstInputDelay":null,"totalBlockingTime":null,"cumulativeLayoutShift":null}],"events":[],"errors":[],"syntheticEvents":[{"name":"navigate to details screen","syntheticEventId":"SYNTHETIC_TEST_STEP-09D1E2CC97B5878B","sequenceNumber":1,"timestamp":1622107547988,"type":"navigate"},{"name":"keystrokes on \"user\"","syntheticEventId":"SYNTHETIC_TEST_STEP-0FCD20FF925F44B1","sequenceNumber":2,"timestamp":1622107550155,"type":"keystrokes"},{"name":"click on next","syntheticEventId":"SYNTHETIC_TEST_STEP-84854E56BAA53321","sequenceNumber":3,"timestamp":1622107551834,"type":"click"},{"name":"keystrokes on \"password\"","syntheticEventId":"SYNTHETIC_TEST_STEP-6CB903FD28430FE6","sequenceNumber":4,"timestamp":1622107553985,"type":"keystrokes"},{"name":"click on login button","syntheticEventId":"SYNTHETIC_TEST_STEP-6400C0C04B6B76E3","sequenceNumber":5,"timestamp":1622107564154,"type":"click"},{"name":"open first event","syntheticEventId":"SYNTHETIC_TEST_STEP-395A7BBE253C8C8C","sequenceNumber":6,"timestamp":1622107566364,"type":"click"},{"name":"select performance part","syntheticEventId":"SYNTHETIC_TEST_STEP-A53F6787F97741F7","sequenceNumber":7,"timestamp":1622107568548,"type":"click"},{"name":"click on \"Analyze performance\"","syntheticEventId":"SYNTHETIC_TEST_STEP-7D9201BEB990247E","sequenceNumber":8,"timestamp":1622107572734,"type":"click"},{"name":"open first execution","syntheticEventId":"SYNTHETIC_TEST_STEP-3A281F8FB8AB3C37","sequenceNumber":9,"timestamp":1622107574905,"type":"click"},{"name":"open screenshot","syntheticEventId":"SYNTHETIC_TEST_STEP-DF43A9A21ADE0E10","sequenceNumber":10,"timestamp":1622107576588,"type":"click"}],"endReason":"END_EVENT","numberOfRageClicks":0,"userExperienceScore":"TOLERATED","connectionType":"UNKNOWN","hasError":true}

7. Download a sample mapping

To export user session data directly to your own Elasticsearch instance, you can download a sample mapping for your indexes by selecting Download mapping. The downloaded template mapping file contains a mapping for each exported field.

The created sample mapping reflects your current settings and can immediately be used when creating the index where user session data are to be exported:

json
PUT /my-usersession-index { "settings": { "index": { "number_of_shards": 3, "number_of_replicas": 1 } }, "mappings": { "properties": { // add the mappings from the downloaded file here ... } } }

Example:

json
{ "mappings" : { "dynamic_templates" : [ { "string_fields" : { "match" : "*", "match_mapping_type" : "string", "mapping" : { "norms" : "false", "type" : "keyword" } } } ], "properties" : { "applicationType" : { "type" : "keyword" }, "appVersion" : { "type" : "keyword" }, // ... } } }

Use Settings 2.0 REST API

The user session export configuration is stored using the Settings 2.0 framework. This provides a REST API that you can use to create, read, update, and delete your endpoint configurations. See Settings API for details.

  • Endpoints to access the Settings API:

    • For Dynatrace SaaS deployments: https://{your-environment-id}.live.dynatrace.com/api/v2/settings/objects/{objectId}
    • For Dynatrace Managed deployments: https://{your-domain}/e/{your-environment-id}/api/v2/settings/objects/{objectId}
    • For Environment ActiveGate: https://{your-activegate-domain}/e/{your-environment-id}/api/v2/settings/objects/{objectId}
  • Address for OpenAPI documentation: https://{your-environment-id}.live.dynatrace.com/rest-api-doc/index.jsp?urls.primaryName=Environment%20API%20v2#/Settings - Objects.

  • Schema ID for the user session export settings: builtin:elasticsearch.user-session-export-settings With this schema ID, you can, for example, read your currently configured user session export settings using any REST client:

    plaintext
    GET /api/v2/settings/object?schemaIds=builtin:elasticsearch.user-session-export-settings&scopes=tenant

To add an endpoint via the REST API:

json
PUT /api/v2/settings/object?schemaIds=builtin:elasticsearch.user-session-export-settings&scopes=tenant { "value": { "values": [{ "basicAuth": { "active": "false" }, "endpointDefinition": { "contentType": "application/json", "enableUserSessionExport": true, "endpointUrl": "https://my-endpoint.com", "usePost": false }, "exportBehavior": { "disableNotification": false }, "sendDirect": { "active": false } }] } }

For details on how to update a settings object, see Settings API - PUT an object.

Troubleshoot

To verify sending data, run the command below. You can set the following additional flags as needed:

  • --insecure - to disable the SSL check
  • --http1.1 - if the command returns a REFUSED_STREAM error
shell
curl -v -H "Content-Type: application/json" -X PUT -d '{"visitorId":"14804637803609BCTKP776NMJBOIF3R8OD6R0E4NQALJO","visitId":"16229530","startTime":1480463779085,"endTime":1480463784889,"visitType":"SYNTHETIC"}' http://localhost:3000/export/events