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:
- Adding a Splunk provider in SquaredUp.
- 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.
- Log on to SquaredUp and navigate to the right-hand menu ☰ then system and then click on the web api perspective.
- Click Add new provider.
-
Change the provider type to basic auth.
- In the service name box type in a suitable name, e.g. Splunk
-
The base URL should look something like
https://instancename:8089/services/search/jobs
whereinstancename
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.
- 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.
- 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.
- Change ignore invalid ssl to on if you are using a self-signed certificate.
- 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
.
- On the top navigation bar in SquaredUp click the + to create a new dashboard, and give your dashboard a title.
-
Click on the Web API tile.
-
Select Web API (Grid).
- Leave the scope section (v4.2 and above) blank for this walkthrough. (The scope is used in last walkthrough in this article).
-
In the provider section select the Splunk provider that you created earlier.
-
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.
-
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 typesearch
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 theWinEventLog
is an index we have created in Splunk,SourceName=HealthService
specifies data from the SCOM HealthService, andType=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 caseoneshot
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 asjson
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 withearliest_time
as-1h
andlatest_time
asnow
, it will return logs from the last hour.name:
max_time
value:30
max_time
is the query timeout limit i.e. 30 seconds. -
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. - Click next
-
In the response data section, type
results
into the box. -
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
- Rename the
host
column toComputer
. -
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.
- Click done.
- Rename the
_time
column toTime Logged
. -
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.
- Click done.
-
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.
- Click done.
- Hide all the other columns to leave just the three you have edited.
- You may wish to change the order the columns to show Computer, Time Logged, Message by dragging them into position.
- Leave the grid options section as it is.
- 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.
Name | Description | Mandatory? |
---|---|---|
search | search followed space and then your Splunk search query |
yes |
exec_mode | Must specify oneshot |
yes |
output_mode | Must specify json |
yes |
timeout | How long Splunk should keep results for (in seconds, e.g.60 ) |
yes |
earliest_time | The earliest result (useful for last x hours, e.g. -1h ) |
no |
latest_time | The latest result, usually just now |
no |
max_time | Query processing timeout limit (in seconds, e.g.30 ) |
no |
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
(whereinstancename
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).