How to use the Web API tile with Splunk

This article covers how to use the Web API tile to query live API data from Splunk and display this in a dashboard or perspective.

SquaredUp uses the Splunk account that you configure and queries will be updated as the page updates, by default every minute.

You can also watch the Webinar: Integrating Splunk

This article covers two areas:

1. Adding a Splunk provider in SquaredUp.
2. Adding a Splunk query to a dashboard.

Prerequisites

• The SquaredUp server must have access to your Splunk instance, since it is the server that connects to Splunk, and not your users' browser.
• A Splunk instance. You may need some help from a Splunk admin to get an account with the correct privileges.

Adding a Splunk provider in SquaredUp

These steps allow you to create a basic auth provider so your specified username and password will be Base64 encoded automatically.

1. Log on to SquaredUp and navigate to the right-hand menu ☰ then system and then click on the web api perspective.
2. Click Add new provider.

3. Change the provider type to basic auth.

   

4. In the service name box type in a suitable name, e.g. Splunk

5. The base URL should look something like https://instancename:8089/services/search/jobs where instancename is your instance. This URL is prepended to every request URL.

   The port number 8089 is the Splunk API port which is different to the port used when browsing Splunk normally, which would be port 8000.

6. If you are using Splunk with Windows authentication you will need to log in to Splunk and add the SquaredUp application pool account to the list of authorized users.
7. If you are using Splunk's built-in authentication enter the username and password for your Splunk instance into the appropriate boxes and they will be Base64 encoded automatically.
8. Change ignore invalid ssl to on if you are using a self-signed certificate.
9. Click add provider.

Walkthrough: Adding a Splunk query to a dashboard

This walkthrough takes you through using a simple Splunk query on a dashboard.

It is important to use http post mode and to set the key path in the response data section to results.

1. On the top navigation bar in SquaredUp click the + to create a new dashboard, and give your dashboard a title.

2. Click on the Web API tile.
   
   

3. Select Web API (Grid).
   
   

4. Leave the scope section (v4.2 and above) blank for this walkthrough. (The scope is used in last walkthrough in this article).

5. In the provider section select the Splunk provider that you created earlier.

   

6. In the http mode section click on post to change the http method from get to post.

   

   The URL shown here is the one you specified in the Web API provider settings above, and is the correct URL for search jobs.

7. The headers & data section is where you can pass key variables through to Splunk. Click the add button under data to add the following data name and value settings:

   name: search value: search index=WinEventLog SourceName=HealthService Type=Error

   search is mandatory because this is where you input your Splunk search query. You need to type search followed by a space and then your Splunk search query string. We recommend you configure your search query in Splunk to check the data returned, then copy the query into SquaredUp. In this example the WinEventLog is an index we have created in Splunk, SourceName=HealthService specifies data from the SCOM HealthService, and Type=Error specifies error messages.

   name: exec_mode value: oneshot

   exec_mode is mandatory as this tells Splunk how to execute the search and what to do with the results. In this case oneshot tells it to search and then send the results back (as opposed to storing them for later).

   name: output_mode value: json

   output_mode is mandatory and must always be set as json so the results are in the correct format. You need this setting in order to see any results.

   name: timeout value: 60

   timeout is mandatory and tells Splunk how long to keep the data after the search has completed. The value is in seconds, and with it set to only 60 we are preventing the Splunk server from filling up with loads of active searches. The default is 24 hours.

   name: earliest_time value: -1h

   earliest_time is how far back the search should go. You can also use UTC strings.

   name: latest_time value: now

   latest_time is when it should run to, so in this case with earliest_time as -1h and latest_time as now, it will return logs from the last hour.

   name: max_time value: 30

   max_time is the query timeout limit i.e. 30 seconds.

8. Click apply changes and the headers & data section should look like this:

   

   At this point you should see a row of data displayed in the tile. The next steps take you into the results data to show more detail. If the tile output is blank check that the http mode section is set to post, and run the query in Splunk to check that data is returned.

9. Click next

10. In the response data section, type results into the box.

    

11. Click next to move to the grid columns section.

    Here we are going to use custom labels to make the data more meaningful. For more information see How to use custom labels

12. Rename the host column to Computer.

13. Click edit next to the Computer column and paste the following in to the custom template box:

    {{value.split('.')[0]}}

    This splits the computer name on the fullstop and only shows the first part.

14. Click done.
15. Rename the _time column to Time Logged.

16. Click edit next to the Time Logged column and paste the following in to the custom template box:

    {{timeago(value)}}

    This shows how long ago the event occurred.
    
    

17. Click done.

18. Click edit next to the Message column and paste the following in to the custom template box:

    {{value.substr(0,230)}}

    This shows only the first 230 characters.

19. Click done.
20. Hide all the other columns to leave just the three you have edited.
21. You may wish to change the order the columns to show Computer, Time Logged, Message by dragging them into position.
22. Leave the grid options section as it is.
23. Click done.

It can be useful to use the clone tile button at the top right of the section to copy the Web API tile you have configured and then make a few changes to the search terms in the headers & data section to add another similar Splunk query to the dashboard.

Reference: headers & data

Each Web API tile you add to a dashboard or perspective can run a different Splunk query. We recommend you configure your search query in Splunk to check the data returned is what you want, then copy the query into SquaredUp. The Splunk search query is specified in the headers & data section, along with other data options, which are described for reference below, and covered step by step in the walkthroughs.

Hints and Tips

• Look at the Splunk API Documentation or speak to your Splunk expert.
• Test your query with PowerShell/Curl/Postman to see the results directly. You can also browse to the URL that you used in your Splunk provider (right-hand menu ☰ > system > web api) which will be something like https://instancename:8089/services/search/jobs (where instancename is your Splunk instance) to see a visual API explorer. Click on services > search jobs you can see the job numbers of any recurring jobs in Splunk, which can then be used in SquaredUp see API explorer.
• Only  SquaredUp administrators are able to create or edit Web API tiles.
• Use custom labels to improve data formatting see How to use custom labels
• You can view a list of the properties available for the search query by going to the monitored entity perspective. (Although displayName is not listed, it is also available for you to use).