The Salesforce event stream extension allows you to monitor the usage of your salesforce environment by the end users.

Get insight into the usage of the Salesforce platform, answering questions like:

What are the slowest Lightning or Classic pages response times What are the most used reports, who is running them, what queries are being used How many users are using the platform currently, what is the user experience What are the top API Queries being made Where is salesforce being accessed from? What is the browser being used?

Requirements

• Salesforce account

  • Event Streaming licensed on salesforce
  • User with View Real-Time Event Monitoring Data user permission.
  • See instructions for enabling event streaming
  • Check that under Setup > Events Manager the events have Streaming Data enabled.
    • The Logout event requires the Customize Application permission as documented here

An example of an account configured with Event Streaming (Setup > Events > Event Manager):

https://dt-cdn.net/hub/event_manager_YeVsnKM.png

There are three steps to install this ActiveGate extension:

1. Environment ActiveGate server - Extract the extension ZIP file to the plugin_deployment folder of the remote plugin module:
   • In a default installation, this is done with

unzip -o -d /opt/dynatrace/remotepluginmodule/plugin_deployment custom.remote.python.salesforce_eventstream.zip - Adjust the path if the ActiveGate was installed somewhere other than /opt/dynatrace 2. Browser - Upload the same extension ZIP file to your tenant. - Settings > Monitored technologies > Custom extensions > Upload extension 3. Define the custom application

Configuration

Create an endpoint for every Salesforce account you want to monitor. This is done at Settings > Monitored technologies > Custom extensions > Salesforce EventStream.

Attention

There are two ways to connect to the Salesforce API:

• Username and Password

  • In this mode, you connect with a specific username.
  • Drawbacks:
    • If the password expires, or the security token changes, you need to update the credentials here.
    • If the user is deleted from Salesforce, this will fail.
  • Advantages:
    • No need to create anything extra in your Salesforce account

• Connected App - In this mode, you connect as a connected app.

  • Drawbacks:

    • You need to create a connected app in your Salesforce account
    • You need to upload a PEM certificate while creating the app, and store the certificate (+key) in a Java Keystore (JKS) that can be read by the Dynatrace user running the extension.

  • Advantages:

    • Not tied to a specific user
    • No user password and no client secrets need to be supplied
    • More secure

The parameters are:

• Openkit beacon URL
  • The beacon URL, you can use the local ActiveGate as the beacon URL with https://localhost:9999/mbeacon/<environment_id>
  • Note that the port could have changed during the ActiveGate installation. By default, it listens on 9999.
• Openkit application ID
  • The application ID of the custom application
• Salesforce username
  • The Salesforce username to log in and listen for events
  • This user needs to have View Real-Time Event Monitoring Data permission
• Salesforce authentication method
  • Connected App or Username + Password
  • Connected App is recommended
• (Username + Password) Salesforce password
  • Only needed if Username + Password authentication is selected
• (Connected App) Consumer key
  • Only needed if Connected App authentication is selected
  • The Consumer Key, displayed in the connected app page
• (Connected App) Audience
  • Only needed if Connected App authentication is selected
  • For regular instances: https://login.salesforce.com
  • For sandbox instances: https://test.salesforce.com
  • For custom communities: https://site.force.com/customers
• (Connected App) JKS path
  • Only needed if Connected App authentication is selected
  • The path to the Java Keystore file that contains the connected app certificate and key
• (Connected App) JKS password
  • Only needed if Connected App authentication is selected
  • The password for the Java Keystore file
• (Connected App) JKS Key Alias
  • Only needed if Connected App authentication is selected
  • The alias for the certificate that is stored in the JKS file
• (Connected App) JKS Key Password
  • Only needed if Connected App authentication is selected
  • The password for the certificate that is stored in the JKS file.
  • This is usually the same password as the JKS file
• (Optional) Salesforce security token
  • The Salesforce Security Token for the user
  • Mandatory if not using mutual certificates
• (Optional) Salesforce instance url
  • Required if using mutual certificates
  • The url to your salesforce instance
  • The port is 8443 if using mutual certificates, usually 443 otherwise
  • Example: https://curious-hawk-3hrbq1-dev-ed.my.salesforce.com:8443
• (Optional) Salesforce client certificate
  • Required if using mutual certificates
  • This is the path to the pem file that has the full certificate chain, example: /var/certs/fullchain.pem
  • Leave empty if you can use user + password + security token
• (Optional) Salesforce client key
  • Required if using mutual certificates
  • This is the path to the pem file that has the certificate key , example: /var/certs/key.pem
• Capture User Information
  • If disabled usernames and IP addresses will not be captured
• Capture LightningUri events
  • If disabled, Dynatrace will not subscribe to /event/LightningUriEventStream events
• Capture API events
  • If disabled, Dynatrace will not subscribe to /event/APIEventStream events
• Capture ListView events
  • If disabled, Dynatrace will not subscribe to /event/ListViewEventStream events
• Capture Uri events
  • If disabled, Dynatrace will not subscribe to /event/UriEventStream events
• Capture Report events
  • If disabled, Dynatrace will not subscribe to /event/ReportEventStream events
• Maximum session age (minutes)
  • End a session that is older than X minutes
  • This is needed for events where a Logout does not happen, ie: API Access
  • Recommended: 1440 minutes (Sessions older than 1 day will be closed and deleted from the cache)
• Log level
• (Optional) Proxy Address
  • Full address including the protocol, example: http://proxy.com:3128
  • Will be used by Openkit as well as the salesforce login
• (Optional) Proxy Username
• (Optional) Proxy Password

Visualization

Real User Monitoring All data is sent using the Real User Monitoring SDK, called Openkit You can view the data under Applications > Application Name.

Custom Device

A Custom Device is also created for troubleshooting purposes only. Technologies > Salesforce Connector > Salesforce Connector (<application_id>) If there are any WARNING messages thrown by the extension, they are sent as Custom Info Events on the Custom Device page. If there are ERROR or FATAL messages, they will open a problem for the same custom device.

This ActiveGate extension uses Openkit to create user sessions based on Salesforce event stream events. This extension reports real user sessions and actions. The data is captured from the Salesforce Event Streaming API.

Properties captured per event

The properties below are captured for the corresponding events. These are displayed in the user action waterfall. Options marked with an * are only captured if Capture user details is enabled. Note that you need to create action or session properties to query these in Dynatrace using UQL.

Login

• AdditionalInfo
• ApiType
• ApiVersion
• Application
• AuthMethodReference
• Browser
• CipherSuite
• ClientVersion
• Country
• CountryIso
• EvaluationTime
• EventDate
• EventIdentifier
• LoginKey
• LoginType
• Platform
• SessionKey
• SessionLevel
• SourceIp*
• Status
• UserId
• Username*
• UserType

Logout

• LoginKey
• SourceIp
• EventDate
• EventIdentifier
• SessionKey
• UserId
• Username
• ReplayId
• SessionLevel

Api

• AdditionalInfo
• ApiType
• ApiVersion
• Application
• Client
• ElapsedTime
• EvaluationTime
• EventDate
• EventIdentifier
• LoginHistoryId
• Operation
• Platform
• PolicyId
• PolicyOutcome
• QueriedEntities
• Query
• Records
• RelatedEventIdentifier
• RowsProcessed
• RowsReturned
• SessionKey
• SessionLevel
• SourceIp*
• UserAgent
• Username*
• UserId

Lightning URI

• AppName
• ConnectionType
• DeviceId
• DeviceModel
• DevicePlatform
• DeviceSessionId
• Duration
• EffectivePageTime
• EventDate
• EventIdentifier
• LoginKey
• Operation
• OsName
• OsVersion
• PageStartTime
• PageUrl
• PreviousPageAppName
• PreviousPageEntityId
• PreviousPageUrl
• QueriedEntities
• RecordId
• RelatedEventIdentifier
• ReplayId
• SdkAppType
• SdkAppVersion
• SdkVersion
• SessionKey
• SessionLevel
• SourceIp*
• UserId
• Username*
• UserType

ListView

• AppName
• ColumnHeaders
• DeveloperName
• EvaluationTime
• EventDate
• EventIdentifier
• EventSource
• ExecutionIdentifier
• FilterCriteria
• ListViewId
• LoginHistoryId
• LoginKey
• Name
• NumberOfColumns
• OrderBy
• OwnerId
• PolicyId
• PolicyOutcome
• QueriedEntities
• Records
• RelatedEventIdentifier
• RowsProcessed
• Scope
• Sequence
• SessionKey
• SessionLevel
• SourceIp*
• UserId
• Username*

Report

• ColumnHeaders
• DashboardId
• DashboardName
• Description
• DisplayedFieldEntities
• EventDate
• EventIdentifier
• EventIdentifier
• EventSource
• ExecutionIdentifier
• ExportFileFormat
• GroupedColumnHeaders
• LoginHistoryId
• LoginKey
• NumberOfColumns
• Operation
• OwnerId
• PolicyId
• PolicyOutcome
• QueriedEntities
• Records
• RelatedEventIdentifier
• ReplayId
• ReportId
• RowsProcessed
• Scheduled
• Scope
• SessionKey
• SessionLevel
• SourceIp*
• UserId
• Username*

Uri

• EventDate
• EventIdentifier
• LoginKey
• Message
• Name
• Operation
• OperationStatus
• QueriedEntities
• RecordId
• RelatedEventIdentifier
• SessionKey
• SessionLevel
• SourceIp*
• UserId
• Username*
• UserType

Supported distributions

Salesforce account with Salesforce Shield or Salesforce Event Monitoring add-on subscription

Licensing consumption

This extension consumes DEM Units. The amount of DEM units depends on the number of Salesforce sessions, as per the table in the documentation.

Get insight into the usage of the Salesforce platform, answering questions like:

• What are the slowest Lightning or Classic page response times?
• What are the most used reports, who is running them, and what queries are used?
• How many users are using the platform currently, and what is the user experience?
• What are the top API queries made?
• From where is Salesforce accessed, and using which browser?

Create a connected app

Requirements

• OpenSSL
• keytool (comes with a Java installation)
• Salesforce account that can create connected apps

Certificates

The connected app will need a certificate attached to it.
You can use an existing certificate or create a new one.

Here are the steps to create a certificate using openssl and keytool.

• Step 1 - Create a certificate and its private key. You can accept all default options.

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem

This will create two files called cert.pem and key.pem.

• Step 2 - Merge both files into one. You can use a text editor, cat, etc.

cat cert.pem key.pem >> full_cert.pem

After this step, you should have a file called full_cert.pem

• Step 3 - Add this certificate to a Java Keystore (jks) file. This will later be used in Dynatrace.

Convert the full_cert.pem file to pkcs12. You must set a password when prompted.

openssl pkcs12 -export -out full_cert.pkcs12 -in full_cert.pem

Add the file to a new Java keystore.
Set a password for the keystore (destination password).
The source password is the one you created with the previous command.

keytool -importkeystore -srckeystore full_cert.pkcs12 -srcstoretype pkcs12 -destkeystore full_cert.jks -deststoretype JKS

After this is done, you should have five files. You will only use two of them:

• key.pem
• cert.pem (Used when creating the connected app in salesforce)
• full_cert.pem
• full_cert.pkcs12
• full_cert.jks (Used by Dynatrace to connect to Salesforce. Must be placed in the ActiveGate file system)

Connected app

In Salesforce Lightning, go to Setup > Apps > App Manager. Select New Connected App.

https://dt-cdn.net/hub/new_connected_app.png

Give the app a name and add the contact email. Under API (Enable OAuth Settings), enable:

• Enable OAuth Settings
• Use digital signatures

The callback URL won't be used. you can use something like http://localhost
Upload the cert.pem file you created under Use digital signatures.

https://dt-cdn.net/hub/app_settings_1.png

Under Selected OAuth Scopes, add:

• The (api) scope, which should be called Manage user data via APIs (api)
• The (refresh_token, offline_access) scope, which should be called Perform requests at any time (refresh_token, offline_access)

The names might differ depending on the version of Salesforce. Use the ones that end with (api) and (refresh_token, offline_access).

https://dt-cdn.net/hub/app_settings_2.png

Leave all other options as is. Select Save.

Now it's time to set up the OAuth Policy permitted users. On the connected app page, select Manage, then Edit Policies.

Under OAuth Policies select Admin approved users are pre-authorized.

https://dt-cdn.net/hub/policy.png

Select Save.

On the same connected app page, under Profiles, select Manage Profiles. Add a profile for users that are approved to use this connected app, like System Administrator.

https://dt-cdn.net/hub/profiles.png

Configure Dynatrace

Place the full_cert.jks file somewhere in the ActiveGate file system.
On Linux, the user dtuserag must be able to read this file.
The path to this file will later be used in the Dynatrace extension configuration page.

For this setup, this is how the endpoint will look in Dynatrace:

Important notes:

• Do not use the lightning URL as the instance. It must be the Classic URL.
• The alias for the certificate inside the JKS you created is 1 because it was not specified.
• The Consumer Key can be copied from Setup > Apps > App Manager > View in Salesforce.

https://dt-cdn.net/hub/endpoint_connected_app.png

Troubleshooting

The logs under %PROGRAMDATA% (windows) or /var/lib (Linux) give you more details if you run into trouble.

The full path is /var/lib/dynatrace/remotepluginmodule/log/remoteplugin/custom.remote.python.salesforce_eventstream/SalesforceEventStream.log

A good example log:

https://dt-cdn.net/hub/log.png

Errors will also be sent to a custom device. Here's an example of an error when using the lightning URL instead of the classic URL:

https://dt-cdn.net/hub/problem_0vw7Eyy.png