Python Object SDK Example

Let's say I want to use Splunk to store and retrieve eBay items for sale.

Class Definition

First we're going to import the splunk Object SDK module, which has the utility classes to read and write objects...

    from objsdk import * 

Next we'll define the EBayListing class, which represents an individual sale on eBay, from eBay's api. The constructor takes a kwargs that assumes all the values needed are passed in...

    class EBayListing(SResult):
        def __init__(self, **kwargs):
            # superclass initialization
            SResult.__init__(self, **kwargs)
            # change '2010-02-21T23:57:49.000Z' to '2010-02-21 23:57:49.000Z'
            self.time     = kwargs['EndTime'].replace("T", " ") 
            self.title    = kwargs['Title']
            self.category = kwargs['PrimaryCategoryName']
            self.url      = kwargs['ViewItemURLForNaturalSearch']
            self.price    = kwargs['ConvertedCurrentPrice']['Value']

Setup

Next we need to register our class, so that the API will return EBayListing objects...

    registerClass(EBayListing)

Next we'll get a session to a Splunk server so we can start putting eBay listing into Splunk and pulling them out...

    s = SSession(username='admin', password='changeme')

Alternatively, you can connect to a Splunk instance running on a different server...

          s = SSession('https://10.1.1.197:8089', 'admin', 'changeme')
    

For the Splunk Free license, you don't even need a username and password...

          s = SSession()
    

By default the Splunk Object SDK processes putting data in asynchronously, so that a get() might not return data that was immediately just put() in. If you'd like get() to block until all put() data is retrievable, set synchronicity to True...

    s.setSynchronous(True)

Storing Objects

Now, assuming we are calling eBay's api to retrieve listing data, we are ready to put() them into Splunk...

    listingAttrs = mycodeToGetListing()
    listing = EBayListing(listingAttrs)
    s.put(listing)

The put() function can take a single listing, as above, or can take a list of objects to put into Splunk in bulk...

    listings = []
    # make 100 EBayListing objects
    for i in range(0,100):
        listingAttrs = mycodeToGetListing()
        listings.append(EBayListing(listingAttrs))
    s.put(listings)

Retrieving Objects

Now that our objects are stored in Splunk, we can search for them and retrieve all EBayListings...

    listings = s.get('EBayListing')
    print "%s listings" % len(listings)
    for listing in listings:
        print "title: %s price: %s" % (listing.title, listing.price)

More sophisticatedly, we can ask for only those items that are PC Desktops that were listed in the last day, but not in the last 5 minutes...

    import time
    recentPCs = s.get('EBayListing', category='Computers & Networking:PC Desktops', 
                      earliest_time="-1d", latest_time="-5m")

Statistical Operations

We can also use Splunk's statistical commands to return statistics about our EBayListings. The 'postsearch' kwarg on the get() method allows processing on the results returns, using the full Splunk search language. Here is an abbreviated cheatsheet on Splunk's search language

Note: here we are no longer dealing with EBayListings as output, because we are asking for statistics about EBayListings. Let's get the average price per product category...

    results = s.get('EBayListing', postsearch='stats avg(price) by category')
    for result in results:
       print "Category: %s AvgPrice: %s" % (result['category'], result['avg(price)'])

The Splunk Object SDK is new, so feedback is appreciated. We'll try to make right any problems you encounter.