Command line examples in the Splunk Enterprise SDK for Python

Examples are located in the /splunk-app-examples/python directory. To run the examples at the command line, use the Python interpreter and include any arguments that are required by the example.

python _examplename_.py --username="admin" --password="yourpassword"

If you saved your login credentials in the .env file, you can omit those arguments:

python _examplename_.py

To get help for an example, use the --help argument with an example:

python _examplename_.py --help

 Run examples

Here are some different command-line examples to show how to use the examples. Make sure Splunk Enterprise is running, and then open a command prompt in the /splunk-app-examples/python directory.

 Run a search and display formatted results

The search.py example runs a search and returns the results, using parameters to customize your searches. Running this example creates a search job that is deleted once the results are returned. Use --help to list the available options. For a deeper description of what these parameters mean, look for them in the Requests table under POST search/jobs in the Splunk REST API documentation.

Here's how to search everything, return results in CSV format, and display progress:

python search.py "search *" --output_mode=csv --verbose=verbose

This example searches everything after a specified time, requires the "desc" field, and returns the first 10 results in JSON format:

python search.py "search * | head 10" --earliest_time="2011-03-12T17:15:00.000-07:00" --rf="desc" --output_mode=json

Use the results.py example to format your search results. This example removes the XML tags and condenses the output, so the results are easier to read than XML. To use this example, pipe a search.py command to a results.py command:

python search.py "search * | head 10" | python results.py

 Run a simple oneshot search

The oneshot.py example is a simpler search example that just runs a search and returns results in the same call (this example hard-codes --exec_mode=oneshot). This example also reformats the XML results automatically. Here's how to search everything and return the first 10 results:

python oneshot.py "search * | head 10"

 Work with search jobs

The job.py example works with search jobs and perform different actions on them. For example, here's how to list your current search jobs:

python job.py list

Here's how to display the properties of a specific job—you specify either the index value or search ID:

python job.py list @4              # Print the fourth job in the queue
python job.py list 1354642929.43   # Print a job specified by a search ID

 Display Splunk system info

The info.py example takes no arguments and simply prints system information about your Splunk instance to the console:

python info.py

 List your data inputs

The inputs.py example enumerates the data inputs that have been set up for your Splunk Enterprise instance, and the properties of each:

python inputs.py

 Upload a data input file

The upload.py example adds a data input file. This command uploads the sampledata.zip file (from the Search Tutorial) to the "test_index" index:

python upload.py /Users/<myusername>/Downloads/sampledata.zip --index="test_index"

 Work with data indexes

The index.py example works with the indexes that store your Splunk data. When you run the index.py example with the list argument alone, it lists all indexes along with the number of events in each:

python index.py list

You can also specify an action (create, clean, enable, disable, reload, update, list) to perform on a specific index. This shows how to list properties for the "test" index:

python index.py list test

This shows how to clean the summary and test indexes:

python index.py clean summary test

 Display events as they are indexed

The stail.py example prints events to the console as they are indexed (the "tail" of a real-time search). For example, this command prints incoming events to the "twitter" index:

python stail.py "search index=twitter"

 Generate sample events for testing

The genevents.py example is a simple event generator that writes 50,000 short time-stamped events to a specified index. You can also specify the way the data is received: over an HTTP connection (stream, the default), over a TCP connection (TCP), or over individually-constructed HTTP connections per event (submit).

For example, this adds events to the "main" index over a TCP connection:

python genevents.py main tcp

Use genevents.py for testing when you need a bunch of events. For example, you can use genevents.py with the stail.py example to display events as they are received in a "test" index. Open two command-prompt windows. In one, enter:

python stail.py "search index=test"

Then, in the other window, enter:

python genevents.py test

 Work with Splunk configuration files

The conf.py example lets you work with Splunk configuration (.conf) files. This command lists the .conf files in $SPLUNK_HOME/etc/system and $SPLUNK_HOME/etc/users (depending on your user account permissions):

python conf.py list

To display the content of a specific .conf file, such as inputs.conf:

python conf.py list inputs

 List Splunk server logging categories

The loggers.py example lists the Splunk server logging categories and their current logging level:

python loggers.py

 Run GET commands for Splunk REST API endpoints

The spurl.py example runs a GET command for any endpoint in the Splunk REST API, and returns the Atom Feed response. These examples use two different endpoints:

python spurl.py /services/data/indexes

python spurl.py /services/saved/searches

 Run Splunk's interactive Python interpreter

The spcmd.py example starts an interactive Python interpreter for the Splunk Enterprise SDK for Python. This interpreter is similar to using the regular Python interpreter, but this Splunk version automatically logs in and connects to your Splunk instance (taking your login credentials from the .splunkrc file:

python spcmd.py

Once the interpreter is running, you can enter single Python commands. For example, next you could run a simple search:

print service.jobs.oneshot("search * | head 10")

Or, list the Splunk apps that are installed:

for app in service.apps: print app.name

To quit the interpreter press Ctrl+D, or enter:

quit()

 List saved event types

The event_types.py example simply lists your saved event types, which are saved searches that do not include a pipe operator or a subsearch.

This lists all of your saved event types:

python event_types.py

 List fired alerts

The fired_alerts.py example lists a summary of the alerts that were fired on the server.

This lists all of your fired alerts:

python fired_alerts.py

 Explore the REST API

The explorer.py example, which is located in the splunk-app-examples/python/explorer directory, lets you interact with all of the endpoints in the Splunk Enterprise REST API from a web page interface. You can select an endpoint, set parameters, and submit the request. If successful, the web page displays the Atom Feed response to the REST API call.

To run this example and launch the explorer.html page in a web browser, open a command prompt in the splunk-app-examples/python/explorer directory and enter:

python explorer.py

 Export indexed events to a file

The export.py example, which is located in the splunk-app-examples/python directory, takes events from an index and saves them to a file, export.out, in the same directory. You can export events in XML, CSV, or JSON format.

This exports the main index:

python export.py --index=main

 Work with saved searches

The SDK includes two examples for working with saved searches:

• The saved_searches.py example, which is located in the /splunk-app-examples/python directory, simply lists your saved searches.
• The saved_search.py example, which is located in the /splunk-app-examples/python/ directory, lets you list your saved searches, but also lets you view properties for a specific saved search and delete a saved search.

From the /splunk-app-examples/python directory, this lists all of your saved searches in an easy-to-read format:

python saved_searches.py

This also lists saved searches, but in the Atom Feed format:

python saved_search/saved_search.py list-all

You can also list the details of one specific search (run one of the previous commands to retrieve names):

python saved_search/saved_search.py list --name="Name of a saved search"

This deletes a saved search:

python saved_search/saved_search.py --operation="delete" --name="Name of a saved search"