Create a search

Create a search

Many calls to Splunk's API involve running some kind of search. For example, you may wish to run a search within Splunk and POST the results to a third party application. Use the search endpoints located at ../services/search/<endpoint>.

When you run a search, Splunk launches a search process asynchronously. This means that you must poll the jobs or events endpoint to see if your search has finished.

Create a search job

Create a search job by POSTing to the search/jobs/ endpoint. Set your search as the POST payload. For example:

curl -u admin:changeme -k https://localhost:8089/services/search/jobs -d"search=search *"

This simple example runs the search for *. It returns an XML response like:

<?xml version='1.0' encoding='UTF-8'?>
<response>
  <sid>1258421375.19</sid>
</response>

You'll need the search ID to retrieve the search, or the number wrapped in <sid></sid>. In the example above this is 1258421375.19.

Check status of a search

Check the status of a search job by hitting the jobs endpoint at search/jobs/. If you know your search's ID, you can add that to the endpoint to get specific information about that search:

curl -u admin:changeme -k https://localhost:8089/services/search/jobs/1258421375.19 

If you're not sure what searches you're running, GET a list of searches from the search/jobs endpoint. This will tell you what searches you're running and the SIDs of the searches.

curl -u admin:changeme -k https://localhost:8089/services/search/jobs/ 

Get search results

Use the results endpoint located at ../services/search/jobs/<sid>/results/ to get your search results. The results endpoint returns when your search is done running. You can also get output from the events endpoint located at ../services/search/jobs/<sid>/events/ while your search is still running. For complete search results, you should use the results endpoint.

You can get your search results in JSON, CSV or XML by setting output_mode=csv. The simplest method is to retrieve searches in CSV format, like this:

curl -u admin:changeme -k https://localhost:8089/services/search/jobs/1258421375.19/results/ -d"output_mode=csv"

Python example

Here's an example of authenticating against a Splunk server and running a search query in Python.

#!/opt/splunk/bin/python -u

import urllib
import httplib2
from xml.dom import minidom

baseurl = 'https://localhost:8089'
userName = 'admin'
password = 'changeme'

searchQuery = 'sourcetype=access_common | head 5'

serverContent = httplib2.Http().request(baseurl + '/services/auth/login',
    'POST', headers={}, body=urllib.urlencode({'username':userName, 'password':password}))[1]

sessionKey = minidom.parseString(serverContent).getElementsByTagName('sessionKey')[0].childNodes[0].nodeValue

# check if the query has the search operator
if not searchQuery.startswith('search'):
    searchQuery = 'search ' + searchQuery

print httplib2.Http().request(baseurl + '/services/search/jobs','POST',
    headers={'Authorization': 'Splunk %s' % sessionKey},body=urllib.urlencode({'search': searchQuery}))[1]

Ruby example

The following example shows how to use Ruby to authenticate against the Splunk REST API with a generic user name and password. Then, run a search, delete a specific search job and list out available search jobs. Note that the list is returned in XML and not parsed. To parse the results from endpoints, use an XML parser such as libxml. Also, you'll need to install the hpricot gem to get this to work.

require 'net/https'
require 'rubygems'
require 'hpricot'

class SplunkClient
  HOST = 'localhost'
  PORT = 8089
  USER = 'admin'
  PASSWORD = 'changeme'

  def splunk_ssl_post_request(path, data = nil, headers = nil)
    http = Net::HTTP.new(HOST, PORT)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    http.post(path, data, headers).body
  end

  def session_key
    @session_key ||= load_session_key
  end

  def load_session_key
    doc = Hpricot(splunk_ssl_post_request("/services/auth/login", "username=#{USER}&password=#{PASSWORD}"))
    (doc/"//sessionkey").inner_html
  end

  def create_job query
    search = "search index=internetmail #{query}"
    splunk_ssl_post_request("/services/search/jobs",
                            "search=#{CGI::escape(search)}",
                            { 'authorization' => "Splunk #{session_key}" })

  end

  def list_jobs
    xml = splunk_ssl_post_request("/services/search/jobs/", nil, {'authorization' => "Splunk #{session_key}"})
    puts xml
  end

  def search_results(sid)
    doc = Hpricot(
      splunk_ssl_post_request("/services/search/jobs/#{sid}/events",
                                          nil,
                                          {'authorization' => "Splunk #{session_key}"}))
    (doc/"/results/result").collect do | result |
      log_text = (result/"field[@k='_raw']/v").inner_text
      Email.new log_text
    end
  end

  def splunk_ssl_delete_request(path, headers = nil)
    http = Net::HTTP.new(HOST, PORT)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    http.delete(path, headers).body
  end
 
  def delete_job(sid)
    splunk_ssl_delete_request("/services/search/jobs/#{sid}",
                            { 'authorization' => "Splunk #{session_key}" })
                            
  end
end

# Here's the actual operating code
client = SplunkClient.new
puts client.list_jobs

Thanks to Patrick Shaughnessy for submitting this example. If you'd like to submit code examples, let us know!

• Was this topic useful?
• Post a comment