Configure user session export
Dynatrace can continually send user session data to a provided webhook endpoint.
To start getting user session data, you need to set up your endpoint and then configure session export via the Dynatrace web UI or via the Settings API.
Dynatrace sends the data on completed user sessions in bulk to all defined endpoints, with a flush every few seconds to export the data as soon as the user session is marked as complete. The data transfer happens 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.
Define your endpoint
The server that provides the webhook needs to listen for PUT or POST requests on a URL specified as part of the session export configuration. Also, for security reasons, Dynatrace allows only HTTPS endpoints.
- HTTP method:
PUTorPOST - Path: as configured
- Content Type:
application/jsonorapplication/x-ndjson. When sending to Elasticsearch, set toapplication/x-ndjson. - Response status code:
200
Configure session export via web UI
To configure user session export via the Dynatrace web UI
- In the Dynatrace menu, go to Settings > Integration > User session exports.
- Select Add item.
- Specify the Endpoint URL, and turn on Enable user session export if you're ready to start receiving the user session data.
For security reasons, Dynatrace allows only HTTPS endpoints.
- Set Content type to
application/jsonorapplication/x-ndjson. When sending session data to Elasticsearch, set it toapplication/x-ndjson. - Turn on Use POST method (instead of PUT) when sending session data to Elasticsearch or when your configured your endpoint to accept
POSTrequests. - optional Configure the authentication, enable data transfer to Elasticsearch, or set up the export scope, alerting, and advanced configuration.
You can also test user session export as well as download a sample dataset or a sample mapping.
You can configure up to three HTTPS endpoints.
Configure authentication
Dynatrace can send user session data using either basic or OAuth 2.0 authentication. These types of authentication enable you to secure your endpoints.
When you activate the authentication for your session export configuration, test the configuration before saving it.
For security reasons, you need to re-enter the basic authentication password or the OAuth 2.0 client secret when testing your session export configuration. You also need to re-enter the password or secret when you edit the existing session export configuration with enabled authentication.
Configure basic authentication
To configure user session export with basic authentication
- On the User session exports page, expand the required endpoint URL.
- Under Authentication, turn on Activate.
- Set Basic authentication as the authentication type.
- Enter your username and password.
The password is encrypted and masked in your environment.
Configure OAuth 2.0 authentication
To configure user session export with OAuth 2.0 client credentials authentication
- On the User session exports page, expand the required endpoint URL.
- Under Authentication, turn on Activate.
- Set OAuth 2.0 as the authentication type.
- Enter your access token URL, client ID, client secret, and scope (optional).
The client secret is encrypted and masked in your environment.
Send data directly to Elasticsearch
To send data directly to your Elasticsearch installation
- Make sure your Elasticsearch instance is reachable from the cluster server. For Dynatrace SaaS deployments, your Elasticsearch instance needs to be publicly available. You can use an SSL certificate and basic or OAuth 2.0 authentication to secure access.
- Make sure your export URL has the following format:
https://<your_host>:9200/_bulk. Replace<your_host>with your actual value. - On the User session exports page, expand the required endpoint URL.
- Under Define your endpoint, make sure that Content type is set to
application/x-ndjsonand that Use POST method (instead of PUT) is turned on. - Under Send data directly to Elasticsearch section, turn on Activate.
- 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 the user session data and define the mapping for your index. See Download a sample mapping for details on how to download a sample mapping for your session export 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 always create the appropriate field mappings. 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
- Specify one single type per index.
- When creating an index, specify an
include_type_namequery string parameter to indicate that requests and responses should include a type name. This parameter defaults totrue. If you don't set it, you get a deprecation warning. If you don't specify any type when creating an index,_docis used.
- Elasticsearch version 7
- Specifying types is deprecated in this Elasticsearch version. The
include_type_nameparameter defaults tofalse. - You can force Elasticsearch to use a type name by setting the parameter to
true, which results in a deprecation warning.
- Specifying types is deprecated in this Elasticsearch version. The
- Elasticsearch version 8
- Specifying types is no longer supported. Starting with this version, omit 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 the Set up export scope, alerting, and advanced configuration section below.
Set up export scope, alerting, and advanced configuration
In the Export scope, alerting, and advanced configuration section of your endpoint, you can narrow down the session export scope, disable the notifications, and adjust some other session export settings.
- Export scope. To define the scope of your user session export, select the required Management zone. After you set up a management zone, Dynatrace sends only those user sessions that have at least one user action with a matching application.
Restricting the session export to synthetic only user sessions isn't currently possible.
- Alerting. Turn on Disable notification if you don't want to receive notifications when your user session export fails.
- Custom configuration. Specify Custom configuration properties to further tweak the user session export configuration. Contact Dynatrace support before changing this field.
If you experience any issues with user session export, contact Dynatrace support before configuring any additional properties.
Test export
To test your user session export configuration, expand the required endpoint URL on the User session exports page, and select Test export.
If the Test export button is disabled, it's likely because your Endpoint URL or Access token URL specifies the HTTP protocol. For security reasons, Dynatrace allows only the HTTPS protocol.
Dynatrace uses the current session export configuration to export up to 50 user sessions for 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 authentication:
- Test your configuration before saving it.
- Re-enter your basic authentication password or the OAuth 2.0 client secret when testing your configuration.
Download a sample dataset
To see what user session data looks like when you export it to your endpoints, expand the required endpoint URL on the User session exports page, and 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 contains user sessions in JSON format, separated by newline characters.
-
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.
Download a sample mapping
To export user session data directly to your own Elasticsearch instance, you can download a sample mapping for your indexes. Expand the required endpoint URL on the User session exports page, and select Download mapping. The downloaded template mapping file contains a mapping for each exported field.
The created sample mapping reflects your current settings, so you can use it when creating the index where user session data is to be exported.
PUT /my-usersession-index
{
"settings": {
"index": {
"number_of_shards": 3,
"number_of_replicas": 1
}
},
"mappings": {
"properties": {
// add the mappings from the downloaded file here ...
}
}
}Configure session export via 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 session export 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}
- For Dynatrace SaaS deployments:
-
Address for OpenAPI documentation:
https://{your-environment-id}.live.dynatrace.com/rest-api-doc/index.jsp?urls.primaryName=Environment%20API%20v2#/Settings%20-%20Objects. -
Schema ID for the user session export configuration:
builtin:elasticsearch.user-session-export-settings-v2.
With this schema ID, you can, for example, read your current user session export configuration using any REST client.GET https://{your-domain}/api/v2/settings/objects?schemaIds=builtin:elasticsearch.user-session-export-settings-v2&scopes=tenant&fields=objectId,value
To add a session export configuration via the REST API
POST https://{your-domain}/api/v2/settings/objects?schemaIds=builtin:elasticsearch.user-session-export-settings-v2&scopes=tenant
[
{
"schemaVersion": "0.0.214",
"schemaId": "builtin:elasticsearch.user-session-export-settings-v2",
"scope": "tenant",
"value": {
"endpointDefinition": {
"endpointUrl": "https://endpoint-export.dev",
"enableUserSessionExport": true,
"contentType": "application/json",
"usePost": false
},
"authentication": {
"active": false
},
"sendDirect": {
"active": false
},
"exportBehavior": {
"managementZone": null,
"disableNotification": false,
"customConfiguration": null
}
}
}
]You can add only one user session export configuration per request. If you need to add a second session export configuration, issue a new POST request.
For details on how to update or delete a settings object, see Settings API - PUT an object and Settings API - DELETE an object.
Troubleshoot
To verify the session export configuration, run the command below. You can set the following additional flags as needed:
--insecureto disable the SSL check--http1.1if the command returns aREFUSED_STREAMerror
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