splunk/splunk-reskit-powershell — pull request #6 by toenuff (2013-08-10 02:40:35+00:00)
Title: Out-Splunk

Out-Splunk is what I think Write-SplunkMessage should be. It allows you to send arbitrary strings of text to Splunk using the InputText parameter. It can also take an inputobject via pipeline or parameter and it will convert the objects into key-value-pairs in a text blob. It currently only supports a single level of an object, i.e, and object and its immediate properties, but nothing nested below that. Additionally, it supports a writecount parameter when using InputObject so that you can save up multiple objects to send in one larger glob of text. This makes sending the data much faster.

I don't think it makes sense to get rid of Write-SplunkMessage because I'm sue that will break things for people, but I think Out-Splunk can be its own cmdlet.

Also, I changed the file I modified to UTF-8 so that we can see the changes made in Git. It probably makes sense to migrate the entire repo at some point - or at least as files get modified.

I did not write the unit test. Because I don't have your environment, I didn't think it was worth the time. If that's a show-stopper, I can get it done at some point.

Pasting the output from Get-Help Out-Splunk -full for quick reference of what the function does and the parameters that are available to it:

NAME
Out-Splunk

SYNOPSIS
Writes data to Splunk from PowerShell

SYNTAX
Out-Splunk [-Computername ] [-Port ] [-Protocol ] [-Timeout ] [-Index ] [-Ho
stname ] -InputObject [-DateProperty ] [-WriteCount ] [-Source ] [-Sour
ceType ] [-Credential ] []

Out-Splunk [-Computername ] [-Port ] [-Protocol ] [-Timeout ] [-Index ] [-Ho
stname ] -InputText [-Source ] [-SourceType ] [-Credential ] []

DESCRIPTION
This cmdlet allows you to write a single-level object or set of objects directly to a Splunk indexer. The objects
will be converted to a format that will allow
Splunk to properly index and create appropriate extract fields. The cmdlet can also be used to send arbirary strin
gs of text to a Splunk indexer.

PARAMETERS
-Computername
This is the name of the Splunk indexer you would like to send dat to.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-Port
This parameter allows you to specify a port to send data to. This module utilizes the REST API for Splunk. Yo
u must ensure that you are specifying the management port.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-Protocol
This parameter allows you to specify whether to use 'http' or 'https' as the protocol to transmit data.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-Timeout
This parameter controls the timeout value to use. This defaults to 1000.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-Index
This parameter allows you to specify the name of the index in Splunk to send data to. If no index is specified,
data will be sent to the index named main on the Splunk server.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-Hostname
This parameter allows you to specify a value to use for Splunk's indexed host field. If no host is specified,
this will default to the name of the computer that is running Out-Splunk.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-InputObject
The set of objects that will be sent to Splunk

Required? true
Position? named
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters?

-DateProperty
The property of the objects in the pipeline that should be indexed by Splunk in the _time field. If you do not
specify a value, the current Date/Time will be used.

Note: Date fields will be picked up as separators by Splunk. Each object should only have one date field or spl
unk will break up the object into multiple events. This
will cause data to be indexed incorrectly. You can workaround this by creating your own custom sourcetype wit
h a transforms/props (in Splunk), and use the InputText
property to format the data exactly as you want it to be presented to the Splunk indexer.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-WriteCount
This is the number of objects that should be grouped together into a single upload to the Splunk indexer. By d
efault this is set to 1. This means that every object
initiates a new connection to the server.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-InputText
This parameter allows you to specify a string of text data to send to Splunk. It does not format the data in a
ny way or add any fields that will be indexed under _time.

Required? true
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-Source
This parameter allows you to specify a value to use for Splunk's indexed Source field. If no source is specifi
ed, this will default to 'Out-Splunk'

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-SourceType
This parameter allows you to specify a value to use for Splunk's indexed SourceType field. If no sourcetype is
specified, this will default to 'Splunk_PowerShell_ResourceKit'. There is no default definition
for 'Out-Splunk' in Splunk. This sourcetype will use the default transforms/props that comes with Splunk. Out
-Splunk with -InputObject will ensure that it submits the data in
a format that will have extract fields for each property.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

-Credential
This allows you to specify a username and password.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters?

This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS
PSObject or String Data

OUTPUTS
This cmdlet has no output

NOTES

NAME: Out-Splunk
AUTHOR: Tome Tanasovski
Version: 1.1
CREATED: 7/11/2012
LASTEDIT:
7/11/2012 1.0
Initial Release
8/9/2013 1.1
Modified to work with latest from Git

-------------------------- EXAMPLE 1 --------------------------

C:\PS>dir |select LastWriteTime, Length, Fullname |Out-Splunk -DateProperty LastWriteTime -Computername 'izvm2db4'
-Credential (Get-Credential)

This will populate the main index on izvm2db4 with a record for every file and directory in the current directory.
The LastWriteTime property for each file/directory will be
indexed as the _time field. Each record will have its SourceType named 'Splunk_PowerShell_ResourceKit' and its Sou
rce will be named 'Out-Splunk'. You will be prompted to enter credentials.

-------------------------- EXAMPLE 2 --------------------------

C:\PS>Import-CSV data.csv |Out-Splunk -DateProperty DateTime -Computername 'adwas09' -Index CSVData -Source data.cs
v -SourceType Data -Credential (get-credential) -WriteCount 10

This will populate the pre-existing CSVData index on adwas09 with a record for every row in the file data.csv. The
columne entitled DateTime will be used as the indexed _time field for each row. Each
record will have its SourceType named 'data.csv' and its source named 'CSVData'. The user will be prompted to speci
fy a username and password when the command is run. The data will be sent 10 rows/events
at a time.

-------------------------- EXAMPLE 3 --------------------------

C:\PS>$data = @"

$(Get-Date)
This=That
Me=You

"@
Out-MSSplunk -InputText $data

This will send the contents of $data to the main index on a splunk server that was connected to via Connect-Splunk.
The source will be Out-Splunk and the sourcetype will be Splunk_PowerShell_ResourceKit.

-------------------------- EXAMPLE 4 --------------------------

C:\PS>Out-Splunk -InputText (get-content c:\file.log) -Source 'c:\file.log'

This will send the contents of c:\file.log to the main index of the Splunk server that was connected to via Connect
-Splunk. The source will be 'c:\file.log' and the sourcetype will be 'Splunk_PowerShell_ResourceKit'.

RELATED LINKS
http://powershell