Collect Logs for the Salesforce App
This page provides instructions for setting up event collection from Salesforce for analysis in Sumo Logic. Click a link to jump to a topic:
- Requirements and process overview
- Configure a new SumoJanus installation for Salesforce
- Sample log message
- Query sample
Requirements and process overview
Before you begin setting up log collection, review the required prerequisites and process overview described in the following sections.
Prerequisites
The Salesforce Event Monitoring add-on is required to obtain all of the data presented in the app dashboards. The add-on enables access all event types in the Salesforce EventLogFile, the LoginEvent object, Transaction Security, and the Event Monitoring Analytics App. For more information, see Get Started with Event Monitoring and Enable Event Monitoring.
Process overview
This page provides instructions for new and upgrade installations:
Configure a new SumoJanus installation for Salesforce
This process includes the following tasks, which must be performed in the order in which they are presented:
- Set Salesforce permissions.
- Install the collector and download the SumoJanus package.
- Deploy the SumoJanus packages.
- Configure the SFDC bundle.
- Configure the JRE path.
- Authenticate with Salesforce.
- Configure a script source.
Step 1: Set Salesforce user permissions
To create a permission set and assign it to a user
- In Salesforce, go to Setup > Administer > Manage Users > Permission Sets.
- Create a permission set with the API Enabled permission and either the View Event Log Files or the View All Data permission. For more information, see Create Permission Sets in Salesforce help.
- On the Permission Set Overview > System Permissions page, select API Enabled and View Event Log Files.
- Click the Manage Assignments button in the permission set you just created, and click Add Assignments.
- Find your user and assign that user to the permission set you just created.
- Save your changes.
Step 2: Install the collector and download the SumoJanus package
In this section you will install a Sumo Logic collector and download the necessary SumoJanus package.
Install the collector
In Sumo Logic, install a Collector (version i19.115 or later) on the system where you want to collect Salesforce Event Monitoring Logs.
Configure an Installed Collector on a Linux or Windows machine. By default the Collector will come with a Java Runtime Environment. To ensure that SumoJanus can locate Java, you may need to update the .bat or .bash file, as described below.
Download the SumoJanus package
The SumoJanus file is required to collect logs from Salesforce. SumoJanus is a proprietary library used for script-based collection from applications such as Okta, Box, and Salesforce.
Use the following SumoJanus package file that is appropriate for your system:
-
For Linux, download sumojanus-salesforce-dist.3.1.0.tar.gz from:
https://script-collection.s3.amazonaws.com/sfdc/r3.1.0/sumojanus-salesforce-dist.3.1.0.tar.gz. - For Windows, download sumojanus-salesforce-dist.3.1.0.zip from
https://script-collection.s3.amazonaws.com/sfdc/r3.1.0/sumojanus-salesforce-dist.3.1.0.zip.
Step 3: Deploy the SumoJanus package
This section provides steps for a new SumoJanus installation.
New SumoJanus installation
-
On Linux, run the following commands:
tar xzvf sumojanus-salesforce-3.1.0.tar.gz
-
On Windows, you can use Windows Explorer to open the zip package and copy it to the target folder.
sumojanus-salesforce-dist.3.1.0.zip
Upgrade an existing SumoJanus installation for Salesforce
- Backup conf/sumologic.properties and the data folder.
- Setup a New SumoJanus installation
- Migrate the backed up conf/sumologic.properties and data folder to the new Janus folder
- Modify the paths in Step 7 below to point to the new folder.
Step 4: Configure the SFDC Bundle
- Go to the unzipped sumojanus-salesforce folder.
- Open the file conf/sumologic.properties and add the following section to the end of the file (do not overwrite any existing content in the file):
[salesforce]
url = <Salesforce Instance URL>
token_file_path = ${path}/data/salesforce.token
record_file_path = ${path}/data/sf_readfiles.dat
# if you are using a SFDC sandbox environment, set the following to true
sandbox = false
interval = daily
- Set the following properties:
-
url—
Point to your Salesforce URL. For example:
https://na25.salesforce.com
sandbox—
If you are is using a sandbox environment, set the property totrue
. It is set tofalse
by default.start_time—
If you don’t specifystart_time
, logs will be collected from two days in the past.interval
—Controls whether you collect daily or hourly logs. Note that later in this procedure, in Step 7: Configure a script source, the setting you specify for Frequency, should correspond to theinterval
setting.
-
In the file conf/sumologic.properties, the following properties are supported.
Property | Required or Default | Description |
url | Required | Instance URL (for example,https://na31.salesforce.com/ |
token_file_path | Required | Path to access token file to authenticate with SFDC API. |
convert_csv_to_json | Not required, default: true | Set to true if output should be in JSON. This is because raw event logs from SF are in CSV format. |
record_file_path | Not required, default: ${path}/sf_readfiles.dat | Path to store list of log event files read successfully. |
sandbox | Not required, default: false | Set to true if the URL points to a sandbox instance. |
start_time | Not required, default: 2 days ago | Milliseconds since the epoch to begin collecting (for example, 1450137600000). |
end_time | Not required, default: now | Milliseconds since the epoch to stop collecting. |
interval |
Not required, default: daily |
Set to daily or hourly for corresponding log files. |
Step 5: Configure the JRE path
On Windows, update SumoJanus_SF.bat
Navigate to the folder where you installed SumoJanus, and open SumoJanus_SF.bat in a text editor. Line 3 of the script sets JAVAPATH
to C:\Program Files\Sumo Logic Collector\jre\bin
as shown below:
set JAVAPATH="C:\Program Files\Sumo Logic Collector\jre\bin"
If your collector JRE is in a different location, update Line 3 accordingly.
On Linux, update SumoJanus_SF.bash
Navigate to the folder where you installed SumoJanus, and open SumoJanus_SF.bash in a text editor. Update the script as follows:
- Add a line that sets
JAVA_HOME
to point to the location of your JRE, just before the last line of the script. For example, if your collector's JRE is in/opt/SumoCollector/jre/bin
, insert this line:
JAVA_HOME=/opt/SumoCollector/jre/bin
-
The last line of the script is:
java -jar ${SUMOJANUS_JAR_FILE} ${runMode} SalesforceCollector-3.1.0.jar -e 1800
Prefix the line with$JAVA_HOME/
, like this:
$JAVA_HOME/java -jar ${SUMOJANUS_JAR_FILE} ${runMode} SalesforceCollector-3.1.0.jar -e 1800
Step 6: Authenticate with Salesforce
After completing the previous steps, you should authenticate the installation with the task outlined in this section.
To authenticate the installation, do the following:
- Log out of SalesForce. >
- Run the following command under the unzipped
sumojanus-salesforce
folder:- On Unix-like systems:
bin/SumoJanus_SF.bash -s
- On Windows:
bin\SumoJanus_SF.bat -s
- On Unix-like systems:
- A browser will open (if it doesn't, see If your browser does not open, below):
- If your browser has already authenticated with Salesforce, a message will display saying that access has been granted.
- Otherwise, you will see the Salesforce login. Supply your credentials (with the required permissions) to grant access.
- You will then see the following message, which says that the token file has been created:
- Don't close the session where you ran
bin/SumoJanus_SF.bash -s
.
If your browser does not open
If the target environment does not have a GUI, for example if you are remoting into the environment, SumoJanus won't be able to open a browser and will print out a link to the CLI instead. Copy that link and paste into a browser. Then follow the authentication and approval process with Salesforce, until you get a URL back that looks like this:
http://localhost:8080/?code=<some_value>&state=<some_value>
Your browser will display error messages like those shown below. You can ignore them.
Copy the URL from the browser, change the protocol from "https" to "http" then use one of the following options ON THE SAME MACHINE where the script is running (in case your browser is actually on a different machine):
- For Linux, open a terminal window and run:
curl -X GET ‘the above url’
- For Windows, open a Powershell window and run:
Invoke-WebRequest ‘the above url’ -Method Get
If everything was successful, you should see the message “Thank you for granting access for SumoLogic SalesforceCollector” somewhere in the return value. If you see an error regarding an expired authorization code instead, make sure you finish this step within 30 seconds of the previous step as noted above.
You should see a confirmation that the token file has been created, similar to the one shown in Step 4 above.
Test your configuration
- To make sure that the settings are correct, run the following command from the
sumojanus-salesforce
folder:- On Unix-like systems:
bin/SumoJanus_SF.bash
- On Windows:
bin\SumoJanus_SF.bat
-s
flag). - On Unix-like systems:
- You should see something like this (which may go on for a while):
- Remove the sf_readfiles.dat file that was just created. This file should be located under the data folder.
Step 7. Configure a script source
In Sumo Logic, configure a Script Source using the instructions in Script Source. Collectors using version 19.245-4 and later do not allow Script Sources to run by default.
For the Sumo Logic App for Salesforce, use the following configuration settings:
- Frequency.
- For daily log files, set frequency to every 6 hours.
- For hourly log files, set frequency to 1 hour.
- Specify a timeout for your command:
- For daily log files, set timeout to every 3 hours.
- For hourly log files, set timeout to 1 hour.
- Command: /bin/bash
- On Unix-like systems:
/bin/bash
- On Windows: Windows Script
- On Unix-like systems:
- Type the full path to the script to execute, for example
- On Unix-like systems:
/opt/SumoCollector/sumojanus/bin/SumoJanus_SF.bash
- On Windows:
c:\Program Files\SumoCollector\sumojanus\bin\SumoJanus_SF.bat
- On Unix-like systems:
- Update the Working Directory
For Working Directory set the full path to the sumojanus folder, for example:- On Unix-like systems:
/opt/SumoCollector/sumojanus
- On Windows:
c:\Program Files\SumoCollector\sumojanus
- On Unix-like systems:
Sample log message
{ "EVENT_TYPE":"Report", "TIMESTAMP":"20171002172229.677", "REQUEST_ID":"423LBHidMGMvdMH5Tie2a-", "ORGANIZATION_ID":"00XT0000000ABmu", "USER_ID":"006X0000006TZhh", "RUN_TIME":"606", "CPU_TIME":"90", "CLIENT_IP":"38.99.50.98", "URI":"/00OE0000003MThb", "REQUEST_STATUS":"S", "DB_TOTAL_TIME":"475884875", "ENTITY_NAME":"", "DISPLAY_TYPE":"S", "RENDERING_TYPE":"W", "REPORT_ID":"00OE0000003MThb", "NUMBER_EXCEPTION_FILTERS":"0", "NUMBER_COLUMNS":"3", "SORT":"", "DB_BLOCKS":"65351", "DB_CPU_TIME":"430", "NUMBER_BUCKETS":"2", "TIMESTAMP_DERIVED":"2016-02-08T21:55:55.667Z", "USER_ID_DERIVED":"006X0000006TZhhIAG", "USER_ID_DERIVED_LOOKUP":"saad@acme.com", "URI_ID_DERIVED":"00OE0000003MThbMAG", "REPORT_ID_DERIVED":"00OE0000003MThbMAG", "REPORT_ID_DERIVED_LOOKUP":"g Current Q MQL(C) by LC" }
Query sample
Most Accessed Reports
_sourceCategory=salesforce event type "Report"
| json "REPORT_ID_DERIVED","REPORT_ID_DERIVED_LOOKUP" as report_id, report_name
| count by report_name, report_id
| format("%s : %s",report_name, report_id) as report_id
| count by report_id
| sort by _count desc | top 20 report_id by _count
- Working Directory:
- On Unix-like systems:
/opt/SumoCollector/sumojanus
- On Windows:
c:\Program Files\SumoCollector\sumojanus
- On Unix-like systems:
- Advanced Options for Logs
- Timezone: Select "UTC".
- Timestamp Format: yyyy-MM-dd'T'HH:mm:ss.SSS
- Timestamp Locator: TIMESTAMP_DERIVED\":\"([^\"]+)\"
-
Download and deploy the SumoJanus package, as described in Step 2 and Step 3.
-
Configure the JRE path, as described in Step 5.
-
From the previous sumojanus folder, copy these files into the corresponding subfolders of the new sumojanus-salesforce folder:
-
conf/sumologic.properties
-
data/salesforce.token
-
data/sf_readfiles.dat
-
- Test your configuration, as described in Step 6.
- From the SumoLogic UI, identify the script source created in Step 7 and modify the path to the script and the working directory so they point to the respective newly created directories.