splunk / splunk-sdk-python

Splunk Software Development Kit for Python
http://dev.splunk.com
Apache License 2.0
698 stars 370 forks source link

Build Status

Reference Docs

The Splunk Enterprise Software Development Kit for Python

Version 2.1.0

The Splunk Enterprise Software Development Kit (SDK) for Python contains library code designed to enable developers to build applications using the Splunk platform.

The Splunk platform is a search engine and analytic environment that uses a distributed map-reduce architecture to efficiently index, search, and process large time-varying data sets.

The Splunk platform is popular with system administrators for aggregation and monitoring of IT machine data, security, compliance, and a wide variety of other scenarios that share a requirement to efficiently index, search, analyze, and generate real-time notifications from large volumes of time-series data.

The Splunk developer platform enables developers to take advantage of the same technology used by the Splunk platform to build exciting new applications.

Getting started with the Splunk SDK for Python

Get started with the Splunk Enterprise SDK for Python

The Splunk Enterprise SDK for Python contains library code, and its examples are located in the splunk-app-examples repository. They show how to programmatically interact with the Splunk platform for a variety of scenarios including searching, saved searches, data inputs, and many more, along with building complete applications.

Requirements

Here's what you need to get going with the Splunk Enterprise SDK for Python.

Install the SDK

Use the following commands to install the Splunk Enterprise SDK for Python libraries. However, it's not necessary to install the libraries to run the unit tests from the SDK.

Use pip:

[sudo] pip install splunk-sdk

Install the Python egg:

[sudo] pip install --egg splunk-sdk

Install the sources you cloned from GitHub:

[sudo] python setup.py install

Testing Quickstart

You'll need docker and docker-compose to get up and running using this method.

make up SPLUNK_VERSION=9.2
make wait_up
make test
make down

To run the examples and unit tests, you must put the root of the SDK on your PYTHONPATH. For example, if you downloaded the SDK to your home folder and are running OS X or Linux, add the following line to your .bash_profile file:

export PYTHONPATH=~/splunk-sdk-python

Following are the different ways to connect to Splunk Enterprise

Using username/password

import splunklib.client as client
service = client.connect(host=<host_url>, username=<username>, password=<password>, autologin=True)

Using bearer token

import splunklib.client as client
service = client.connect(host=<host_url>, splunkToken=<bearer_token>, autologin=True)

Using session key

import splunklib.client as client
service = client.connect(host=<host_url>, token=<session_key>, autologin=True)

Update a .env file

To connect to Splunk Enterprise, many of the SDK examples and unit tests take command-line arguments that specify values for the host, port, and login credentials for Splunk Enterprise. For convenience during development, you can store these arguments as key-value pairs in a .env file. Then, the SDK examples and unit tests use the values from the .env file when you don't specify them.

Note: Storing login credentials in the .env file is only for convenience during development. This file isn't part of the Splunk platform and shouldn't be used for storing user credentials for production. And, if you're at all concerned about the security of your credentials, enter them at the command line rather than saving them in this file.

here is an example of .env file:

# Splunk Enterprise host (default: localhost)
host=localhost
# Splunk Enterprise admin port (default: 8089)
port=8089
# Splunk Enterprise username
username=admin
# Splunk Enterprise password
password=changed!
# Access scheme (default: https)
scheme=https
# Your version of Splunk Enterprise
version=9.2
# Bearer token for authentication
#splunkToken=<Bearer-token>
# Session key for authentication
#token=<Session-Key>

SDK examples

Examples for the Splunk Enterprise SDK for Python are located in the splunk-app-examples repository. For details, see the Examples using the Splunk Enterprise SDK for Python on the Splunk Developer Portal.

Run the unit tests

The Splunk Enterprise SDK for Python contains a collection of unit tests. To run them, open a command prompt in the /splunk-sdk-python directory and enter:

make

You can also run individual test files, which are located in /splunk-sdk-python/tests. To run a specific test, enter:

make test_specific

The test suite uses Python's standard library, the built-in unittest library, pytest, and tox.

Notes:

  • The test run fails unless the SDK App Collection app is installed.
  • To exclude app-specific tests, use the make test_no_app command.
  • To learn about our testing framework, see Splunk Test Suite on GitHub. In addition, the test run requires you to build the searchcommands app. The make command runs the tasks to do this, but more complex testing may require you to rebuild using the make build_app command.

Repository

Directory Description
/docs Source for Sphinx-based docs and build
/splunklib Source for the Splunk library modules
/tests Source for unit tests
/utils Source for utilities shared by the unit tests

Customization

Do

class CustomStreamingCommand(StreamingCommand):
    def stream(self, records):
        for index, record in enumerate(records):
            if index % 1 == 0:
                self.add_field(record, "odd_record", "true")
            yield record

Don't

class CustomStreamingCommand(StreamingCommand):
    def stream(self, records):
        for index, record in enumerate(records):
            if index % 1 == 0:
                record["odd_record"] = "true"
            yield record

Customization for Generating Custom Search Command

Do

@Configuration()
class GeneratorTest(GeneratingCommand):
    def generate(self):
        yield self.gen_record(_time=time.time(), one=1)
        yield self.gen_record(_time=time.time(), two=2)

Don't

@Configuration()
class GeneratorTest(GeneratingCommand):
    def generate(self):
        yield {'_time': time.time(), 'one': 1}
        yield {'_time': time.time(), 'two': 2}

Access metadata of modular inputs app

Access service object in Custom Search Command & Modular Input apps

Custom Search Commands

Modular Inputs app:

Optional:Set up logging for splunklib

import logging
from splunklib import setup_logging

# To see debug and above level logs
setup_logging(logging.DEBUG)

Changelog

The CHANGELOG contains a description of changes for each version of the SDK. For the latest version, see the CHANGELOG.md on GitHub.

Branches

The master branch represents a stable and released version of the SDK. To learn about our branching model, see Branching Model on GitHub.

Documentation and resources

Resource Description
Splunk Developer Portal General developer documentation, tools, and examples
Integrate the Splunk platform using development tools for Python Documentation for Python development
Splunk Enterprise SDK for Python Reference SDK API reference documentation
REST API Reference Manual Splunk REST API reference documentation
Splunk>Docs General documentation for the Splunk platform
GitHub Wiki Documentation for this SDK's repository on GitHub
Splunk Enterprise SDK for Python Examples Examples for this SDK's repository

Community

Stay connected with other developers building on the Splunk platform.

Contributions

If you would like to contribute to the SDK, see Contributing to Splunk. For additional guidelines, see CONTRIBUTING.

Support

Contact Us

You can reach the Splunk Developer Platform team at devinfo@splunk.com.

License

The Splunk Enterprise Software Development Kit for Python is licensed under the Apache License 2.0. See LICENSE for details.