The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.
This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Sumo Logic.
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.
Check out our built-in integration
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 configure this integration using the Integration Directory, see our online integration guide for Sumo Logic.
To continue setting up this packaged integration, use the following steps.
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 user who can authenticate REST web service calls when injecting events.
This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the required permissions and capabilities.
Note: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.
To create an integration user:
- Log in to the target xMatters system.
- On the Users tab, click Add.
- Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in the reports and Communication Center, you may want to identify the user as specific to Sumo Logic; for example:
- First Name: SumoLogic
- Last Name: Integration
- User ID: sumologic
- Assign the user to the REST Web Service User role.
- Set the password for the user.
- Make a note of the user ID and password details; you need them when configuring other parts of the integration.
- Click Add.
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 Choose File, and then locate the downloaded communication plan (the .zip file).
- Click Import Plan.
- Click the Edit drop-down list for the plan, and select Access Permissions.
- Add the integration user you created above, and then click Save Changes.
- In the Edit drop-down list, select Forms.
- For the Sumo Logic Event form, in the Web Service drop-down list, click Sender Permissions.
- Enter the integration user you created above, and then click Save Changes.
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 select 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.
- Under the Select authentication method step, select Basic Authentication, then click Update Inbound Integration.
- Scroll down to the bottom of the page, and click Copy URL beside the field:
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 each field.
|Name||The name of the Connection. This is displayed when creating the Saved Search.|
|Description||A descriptive statement about the connection.|
|URL||The URL for the "Inbound Webhook" inbound integration.|
Enter the base64-encoded username and password of the integration user here. You can create this value by following the instructions below:
If URL authentication was used for the inbound integration, enter NONE. An empty value here causes 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:
The next step is to create a new Saved Search that, when triggered, firse 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 (see the table below for details on each field):
|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 Create a new Connection section above.|
|Payload||This is automatically populated from the connection.|
- Click Save.
Testing the integration depends 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 is displayed in the Sumo Logic UI marking the new information.
A new event is created in xMatters, targeting the recipient in the form layout. Here's an example of an email or push message alert:
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.
If there is no entry here, then Sumo Logic didn't make the call to xMatters. Review the xMatters Connection and verify the Authorization.