splunklib.modularinput

The following imports allow these classes to be imported via the splunklib.modularinput package like so:

from splunklib.modularinput import *

class splunklib.modularinput.Argument(name, description=None, validation=None, data_type='STRING', required_on_edit=False, required_on_create=False, title=None)

Class representing an argument to a modular input kind.

Argument is meant to be used with Scheme to generate an XML definition of the modular input kind that Splunk understands.

name is the only required parameter for the constructor.

Example with least parameters:

arg1 = Argument(name="arg1")

Example with all parameters:

arg2 = Argument(
    name="arg2",
    description="This is an argument with lots of parameters",
    validation="is_pos_int('some_name')",
    data_type=Argument.data_type_number,
    required_on_edit=True,
    required_on_create=True
)

Parameters:

• name – string, identifier for this argument in Splunk.
• description – string, human-readable description of the argument.
• validation – string specifying how the argument should be validated, if using internal validation. If using external validation, this will be ignored.
• data_type – string, data type of this field; use the class constants. “data_type_boolean”, “data_type_number”, or “data_type_string”.
• required_on_edit – Boolean, whether this arg is required when editing an existing modular input of this kind.
• required_on_create – Boolean, whether this arg is required when creating a modular input of this kind.
• title – String, a human-readable title for the argument.

add_to_document(parent)

Adds an Argument object to this ElementTree document.

Adds an <arg> subelement to the parent element, typically <args> and sets up its subelements with their respective text.

Parameters:parent – An ET.Element to be the parent of a new <arg> subelement Returns:An ET.Element object representing this argument.

class splunklib.modularinput.Event(data=None, stanza=None, time=None, host=None, index=None, source=None, sourcetype=None, done=True, unbroken=True)

Represents an event or fragment of an event to be written by this modular input to Splunk.

To write an input to a stream, call the write_to function, passing in a stream.

There are no required parameters for constructing an Event

Example with minimal configuration:

my_event = Event(
    data="This is a test of my new event.",
    stanza="myStanzaName",
    time="%.3f" % 1372187084.000
)

Example with full configuration:

excellent_event = Event(
    data="This is a test of my excellent event.",
    stanza="excellenceOnly",
    time="%.3f" % 1372274622.493,
    host="localhost",
    index="main",
    source="Splunk",
    sourcetype="misc",
    done=True,
    unbroken=True
)

Parameters:

• data – string, the event’s text.
• stanza – string, name of the input this event should be sent to.
• time – float, time in seconds, including up to 3 decimal places to represent milliseconds.
• host – string, the event’s host, ex: localhost.
• index – string, the index this event is specified to write to, or None if default index.
• source – string, the source of this event, or None to have Splunk guess.
• sourcetype – string, source type currently set on this event, or None to have Splunk guess.
• done – boolean, is this a complete Event? False if an Event fragment.
• unbroken – boolean, Is this event completely encapsulated in this Event object?

write_to(stream)

Write an XML representation of self, an Event object, to the given stream.

The Event object will only be written if its data field is defined, otherwise a ValueError is raised.

Parameters:stream – stream to write XML to.

class splunklib.modularinput.EventWriter(output=<open file '<stdout>', mode 'w' at 0x10028c150>, error=<open file '<stderr>', mode 'w' at 0x10028c1e0>)

EventWriter writes events and error messages to Splunk from a modular input. Its two important methods are writeEvent, which takes an Event object, and log, which takes a severity and an error message.

Parameters:

• output – Where to write the output; defaults to sys.stdout.
• error – Where to write any errors; defaults to sys.stderr.

close()

Write the closing </stream> tag to make this XML well formed.

log(severity, message)

Logs messages about the state of this modular input to Splunk. These messages will show up in Splunk’s internal logs. :param severity: string, severity of message, see severities defined as class constants. :param message: string, message to log.

write_event(event)

Writes an Event object to Splunk.

Parameters:event – An Event object.

write_xml_document(document)

Writes a string representation of an ElementTree object to the output stream.

Parameters:document – An ElementTree object.

class splunklib.modularinput.InputDefinition

InputDefinition encodes the XML defining inputs that Splunk passes to a modular input script.

Example:

i = InputDefinition()

static parse(stream)

Parse a stream containing XML into an InputDefinition.

Parameters:stream – stream containing XML to parse. Returns:definition: an InputDefinition object.

class splunklib.modularinput.Scheme(title)

Class representing the metadata for a modular input kind.

A Scheme specifies a title, description, several options of how Splunk should run modular inputs of this kind, and a set of arguments which define a particular modular input’s properties.

The primary use of Scheme is to abstract away the construction of XML to feed to Splunk.

Parameters:title – string identifier for this Scheme in Splunk.

add_argument(arg)

Add the provided argument, arg, to the self.arguments list.

Parameters:arg – An Argument object to add to self.arguments.

to_xml()

Creates an ET.Element representing self, then returns it.

Returns:an ET.Element representing this scheme.

class splunklib.modularinput.Script

An abstract base class for implementing modular inputs.

Subclasses should override get_scheme, stream_events, and optionally validate_input if the modular input uses external validation.

The run function is used to run modular inputs; it typically should not be overridden.

get_scheme()

The scheme defines the parameters understood by this modular input.

Returns:a Scheme object representing the parameters for this modular input.

run(args)

Runs this modular input

Parameters:args – List of command line arguments passed to this script. Returns:An integer to be used as the exit value of this program.

run_script(args, event_writer, input_stream)

Handles all the specifics of running a modular input

Parameters:

• args – List of command line arguments passed to this script.
• event_writer – An EventWriter object for writing events.
• input_stream – An input stream for reading inputs.

Returns:

An integer to be used as the exit value of this program.

service

Returns a Splunk service object for this script invocation.

The service object is created from the Splunkd URI and session key passed to the command invocation on the modular input stream. It is available as soon as the Script.stream_events method is called.

Returns:splunklib.client.Service. A value of None is returned, if you call this method before the Script.stream_events method is called.

stream_events(inputs, ew)

The method called to stream events into Splunk. It should do all of its output via EventWriter rather than assuming that there is a console attached.

Parameters:

• inputs – An InputDefinition object.
• ew – An object with methods to write events and log messages to Splunk.

validate_input(definition)

Handles external validation for modular input kinds.

When Splunk calls a modular input script in validation mode, it will pass in an XML document giving information about the Splunk instance (so you can call back into it if needed) and the name and parameters of the proposed input.

If this function does not throw an exception, the validation is assumed to succeed. Otherwise any errors thrown will be turned into a string and logged back to Splunk.

The default implementation always passes.

Parameters:definition – The parameters for the proposed input passed by splunkd.

class splunklib.modularinput.ValidationDefinition

This class represents the XML sent by Splunk for external validation of a new modular input.

Example:

v = ValidationDefinition()

static parse(stream)

Creates a ValidationDefinition from a provided stream containing XML.

The XML typically will look like this:

<items>
   <server_host>myHost</server_host>
     <server_uri>https://127.0.0.1:8089</server_uri>
     <session_key>123102983109283019283</session_key>
     <checkpoint_dir>/opt/splunk/var/lib/splunk/modinputs</checkpoint_dir>
     <item name="myScheme">
       <param name="param1">value1</param>
       <param_list name="param2">
         <value>value2</value>
         <value>value3</value>
         <value>value4</value>
       </param_list>
     </item>
</items>

Parameters:stream – Stream containing XML to parse. Returns:A ValidationDefinition object.