This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Sumo Logic.
How it works
Sumo Logic is the next generation log management and analytics company that leverages Big Data for real-time IT insights. The company’s cloud-based service provides customers with real-time interactive analytics at unprecedented petabyte scale.
The integration with xMatters extends the massive searching power of Sumo Logic and delivers the right information to the right person at the right time. Users search for terms using the Sumo Logic Query Language, then save the search for future use.
With real time processing, any new log entries that satisfy the search criteria trigger the saved search and fire a Webhook to xMatters. The Integration Builder then transforms the payload into an event, and notifies the targeted recipient.
A note to xMatters trial users:If you are using the trial version of xMatters, you can install a "built-in" version of this integration using the Integration Directory (Developer tab > Integrations). Built-in integrations are pre-configured for your xMatters: you don't need to download and import the communication plan, or follow the directions to configure xMatters as described below.
To continue configuring this integration for your trial version of xMatters, skip ahead to Configure the integration.
Download the communication plan
This integration includes a communication plan specifically tailored for Sumo Logic. To begin, download the communication plan attached to this article to a location on your local machine. (You do not need to extract the contents.)
The first step in setting up your integration is to configure xMatters.
This integration requires a REST API user to authenticate REST web service calls when injecting events.
This user needs to be able to work with events, but not update administrative settings. The best way to create a user for this integration is to have a dedicated "REST Web Service User" role that includes the permissions and capabilities. If this role does not exist in your deployment, you will need to create it, or ask your xMatters Client Success Manager to create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)
In the following example, this role is named "REST Web Service User".
To create a REST API user:
- Log in to the target xMatters system.
- On the Users tab, click the Add New User icon.
- Enter the appropriate information for your new user.
- Assign the user to the REST Web Service User role.
- Click Save.
- On the next page, set the web login ID and password.
The integration with Sumo Logic requires users and/or groups to exist in xMatters.using the EPIC feature.
The next step is to import the communication plan.
To import the communication plan:
- In the target xMatters system, on the Developer tab, click Import Plan.
- Click Browse, and then locate the downloaded communication plan, Sumo-Logic-Comm-Plan.zip.
- Click Import Plan.
- Once the communication plan has been imported, click Plan Disabled to enable the plan.
- In the Edit drop-down list, select Forms.
- For the Sumo Logic Event form, in the Not Deployed drop-down list, click Create Event Web Service.
- After you create the web service, the drop-down list label will change to Web Service Only.
- In the Web Service Only drop-down list, click Permissions.
- Enter the REST API user you created above, and then click Save Changes.
To get the web service URL for a form, in the Web Service Only drop-down list, click Access Web Service URL. Copy the highlighted URL at the top of the dialog box.
Note: The Access Web Service URL option appears twice in the drop-down menu. Ensure that you click the option just below Create Event Web Service.
You'll need these URLs when you configure the rest of the integration.
The targeted recipient is defined on the form layout.
To configure the targeted recipient:
- Click the Forms tab inside the Sumo Logic communications plan.
- Click the Edit drop down next to the Sumo Logic Event form and click Layout.
- In the Recipients box type the name of the Group, User or Device the integration should target
- Click Save Changes.
Next, configure the inbound integration in the Integration Builder.
To configure the inbound integration:
- Click the Integration Builder tab inside the Sumo Logic communication plan.
- Click Edit Endpoints.
- For the xMatters endpoint, assign it to the REST API user you created above.
- This will allow the integration script to authenticate against the Sumo Logic form.
- For more information about the Authentication feature of the Integration Builder, refer to the Integration Builder online help.
Now that you've configured xMatters to integrate with your system, it's time to configure your system to integrate with xMatters.
First, in Sumo Logic, create a new Connection by clicking Manage > Connections. Connections facilitate the communications between Sumo Logic and xMatters. These are then referenced as the target when creating a Saved Search
Click the Add+ button at the top to display a list of connection types, and then click Webhook:
Enter the required details; see the table below the image for details on what field does what.
|Name||The name of the Connection. This will be displayed when creating the Saved Search.|
|Description||A descriptive statement about the connection.|
The Web Service URL for the "Inbound Webhook" integration service above.
For trial users, the integration URL is available in the Configure Sumo Logic section of the integration configuration screen:
If authentication is enabled on the Inbound Webhook, enter the base64-encoded username and password here. If no authentication is needed, enter NONE.
An empty value here will cause errors in the Integration Service.
This is the payload that will be sent to the Integration Builder. Copy the following text and paste it into the Payload field:
For trial users, the identical payload is also available in the Configure Sumo Logic section of the integration configuration screen.
The next step is to create a new Saved Search that, when triggered, will fire a new event to xMatters. Enter the search criteria into the Sumo Logic search bar, and then click the Save As link.
Enter the appropriate information, and then click the Schedule this search link.
In the Schedule this search dialog box, enter the following information (details on each field are below the image):
|Run Frequency||Select Real Time to ensure that, as the results are found, the information is immediately sent to xMatters.|
|Time range for scheduled search||Depending on the window of the Connector retrieving the information, this might have to be set to a larger time range. In testing, 2 minutes was acceptable.|
|Alert Condition||Choose the alert condition. If the notification needs to go out for any occurrence of the search, choose Greater than or equal to 1.|
|Alert Type||Choose Webhook.|
|Webhook||Choose the webhook that was created in the Connections section above.|
|Payload||This will be automatically populated.|
Testing the integration will depend on the nature of the collector, the search criteria and the infrastructure. The following test scenario assumes a file called "mysumo.log" is collected by a collector.
To test the integration:
Open a terminal to the target box, and type the following into the command line:
$ echo "$(date +"%b %d %T") The cookies are on fire. Save the butter" | cat >> /var/log/mysumo.log
Shortly after, a new entry will be displayed in the Sumo Logic UI marking the new information.
A new event will be created in xMatters targeting the recipient in the form layout. An email or push message alert will look like this:
The first place to look is the Activity Stream on the Integration Builder for the "Inbound Webhook" inbound integration. If there is an entry here, Sumo Logic successfully made the call to xMatters. Inspect the details for any errors. For trial users, check the Events Report.
If there is no entry here, then Sumo Logic didn't make the call to xMatters. Review the xMatters Connection and verify the Authorization and Endpoint URL fields.