Sumo Logic Integration

Contents

Introduction

Configure xMatters

Configure the integration

Test the integration

Download resources

Introduction

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.)

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Create a REST API user

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:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user.
  4. Assign the user to the REST Web Service User role.
  5. Click Save.
  6. On the next page, set the web login ID and password. 
Make a note of these details; you will need them when configuring other parts of this integration.

Create users and groups that will receive notifications

The integration with Sumo Logic requires users and/or groups to exist in xMatters.

You can create multiple groups and users at once using the EPIC feature. 
 

Import the communication plan

The next step is to import the communication plan.

To import the communication plan:

  1. In the target xMatters system, on the Developer tab, click Import Plan.
  2. Click Browse, and then locate the downloaded communication plan, Sumo-Logic-Comm-Plan.zip.
  3. Click Import Plan.
  4. Once the communication plan has been imported, click Plan Disabled to enable the plan.
  5. In the Edit drop-down list, select Forms.
  6. 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.
  7. In the Web Service Only drop-down list, click Permissions.
  8. Enter the REST API user you created above, and then click Save Changes.

Accessing web service URLs

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.

Set the targeted recipient

The targeted recipient is defined on the form layout. 

To configure the targeted recipient:

  1. Click the Forms tab inside the Sumo Logic communications plan.
  2. Click the Edit drop down next to the Sumo Logic Event form and click Layout.
  3. In the Recipients box type the name of the Group, User or Device the integration should target
  4. Click Save Changes. 

Configuring the inbound integration

Next, configure the inbound integration in the Integration Builder.

To configure the inbound integration:

  1. Click the Integration Builder tab inside the Sumo Logic communication plan.
  2. Click Edit Endpoints.
  3. 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. 
  4. Click Save Changes.
  5. If authentication with Sumo Logic is required, click Authentication OFF, and then capture the username and password supplied in the Authentication dialog box. These will be used below, in the Authorization Header field of the Sumo Logic connection.
  6. Click the gear icon for the Inbound Webhook integration and then click Integration URL. Copy the URL to a text file for later: you will need it in the next section. 

Configure the integration

Now that you've configured xMatters to integrate with your system, it's time to configure your system to integrate with xMatters. 

Create a New Connection

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.

 

Field descriptions

Field Value
Name The name of the Connection. This will be displayed when creating the Saved Search. 
Description A descriptive statement about the connection. 
URL

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:

Authorization Header

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 value will need to be base64 encoded. See here for an example.

Payload

This is the payload that will be sent to the Integration Builder. Copy the following text and paste it into the Payload field:

{
  "SearchName": "$SearchName",
  "SearchDescription": "$SearchDescription",
  "SearchQuery": "$SearchQuery",
  "SearchQueryUrl": "$SearchQueryUrl",
  "TimeRange": "$TimeRange",
  "FireTime": "$FireTime",
  "AggregateResultsJson": "$AggregateResultsJson",
  "RawResultsJson": "$RawResultsJson",
  "NumRawResults": "$NumRawResults"
}

For trial users, the identical payload is also available in the Configure Sumo Logic section of the integration configuration screen.




 

 

Create a New Saved Search

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):

 

Field Value
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. 




 
Click Save.  

 

Test the integration

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:

 

 

Troubleshooting

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. 

 

Download resources

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk