README
¶
Go-Splunk-HTTP
A simple and lightweight HTTP Splunk logging package for Go. Instantiates a logging connection object to your Splunk server and allows you to submit log events as desired. Uses HTTP event collection on a Splunk server.
Table of Contents
Installation
go get "github.com/ZachtimusPrime/Go-Splunk-HTTP/splunk"
Usage
Construct a new Splunk HTTP client, then send log events as desired.
For example:
package main
import "github.com/ZachtimusPrime/Go-Splunk-HTTP/splunk"
func main() {
// Create new Splunk client
splunk := splunk.NewClient(
nil,
"https://{your-splunk-URL}:8088/services/collector",
"{your-token}",
"{your-source}",
"{your-sourcetype}",
"{your-index}"
)
// Use the client to send a log with time auto-generated by go host [ time.Now().Unix() ]
err := splunk.Log(
interface{"msg": "send key/val pairs or json objects here", "msg2": "anything that is useful to you in the log event"}
)
if err != nil {
return err
}
// Use the client to send a log with time passed by source
err = splunk.LogWithTime(
1514764800,
interface{"msg": "send key/val pairs or json objects here", "msg2": "anything that is useful to you in the log event"}
)
if err != nil {
return err
}
// Use the client to send a batch of log events
var events []splunk.Event
events = append(
events,
splunk.NewEvent(
interface{"msg": "event1"},
"{desired-source}",
"{desired-sourcetype}",
"{desired-index}"
)
)
events = append(
events,
splunk.NewEvent(
interface{"msg": "event2"},
"{desired-source}",
"{desired-sourcetype}",
"{desired-index}"
)
)
err = splunk.LogEvents(events)
if err != nil {
return err
}
}
Splunk Writer
To support logging libraries, and other output, we've added an asynchronous Writer. It supports retries, and different intervals for flushing messages & max log messages in its buffer
The easiest way to get access to the writer with an existing client is to do:
writer := splunkClient.Writer()
This will give you an io.Writer you can use to direct output to splunk. However, since the io.Writer() is asynchronous, it will never return an error from its Write() function. To access errors generated from the Client, Instantiate your Writer this way:
splunk.Writer{
Client: splunkClient
}
Since the type will now be splunk.Writer(), you can access the Errors() function, which returns a channel of errors. You can then spin up a goroutine to listen on this channel and report errors, or you can handle however you like.
Optionally, you can add more configuration to the writer.
splunk.Writer {
Client: splunkClient,
FlushInterval: 10 *time.Second, // How often we'll flush our buffer
FlushThreshold: 25, // Max messages we'll keep in our buffer, regardless of FlushInterval
MaxRetries: 2, // Number of times we'll retry a failed send
}
Documentation
¶
Index ¶
- Constants
- type Client
- func (c *Client) Log(event interface{}) error
- func (c *Client) LogEvent(e *Event) error
- func (c *Client) LogEvents(events []*Event) error
- func (c *Client) LogWithTime(t int64, event interface{}) error
- func (c *Client) NewEvent(event interface{}, source string, sourcetype string, index string) *Event
- func (c *Client) NewEventWithTime(t int64, event interface{}, source string, sourcetype string, index string) *Event
- func (c *Client) Writer() *Writer
- type Event
- type Hook
- type RemoteSplunkError
- type Writer
Constants ¶
const (
SplunkResponseBodySnippetMaxLength = 128
)
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
HTTPClient *http.Client // HTTP client used to communicate with the API
URL string
Hostname string
Token string
Source string // Default source
SourceType string // Default source type
Index string // Default index
}
Client manages communication with Splunk's HTTP Event Collector. New client objects should be created using the NewClient function.
The URL field must be defined and pointed at a Splunk servers Event Collector port (i.e. https://{your-splunk-URL}:8088/services/collector). The Token field must be defined with your access token to the Event Collector. The Source, SourceType, and Index fields must be defined.
func NewClient ¶
func NewClient(httpClient *http.Client, url string, token string, source string, sourceType string, index string) *Client
NewClient creates a new client to Splunk. This should be the primary way a Splunk client object is constructed.
func (*Client) Log ¶
Client.Log is used to construct a new log event and POST it to the Splunk server.
All that must be provided for a log event are the desired map[string]string key/val pairs. These can be anything that provide context or information for the situation you are trying to log (i.e. err messages, status codes, etc). The function auto-generates the event timestamp and hostname for you.
func (*Client) LogEvents ¶
Client.LogEvents is used to POST multiple events with a single request to the Splunk server.
func (*Client) LogWithTime ¶
Client.LogWithTime is used to construct a new log event with a scpecified timestamp and POST it to the Splunk server.
This is similar to Client.Log, just with the t parameter.
func (*Client) NewEvent ¶
NewEvent creates a new log event to send to Splunk. This should be the primary way a Splunk log object is constructed, and is automatically called by the Log function attached to the client. This method takes the current timestamp for the event, meaning that the event is generated at runtime.
func (*Client) NewEventWithTime ¶
func (c *Client) NewEventWithTime(t int64, event interface{}, source string, sourcetype string, index string) *Event
NewEventWithTime creates a new log event with a specified timetamp to send to Splunk. This is similar to NewEvent but if you want to log in a different time rather than time.Now this becomes handy. If that's the case, use this function to create the Event object and the the LogEvent function.
type Event ¶
type Event struct {
Time int64 `json:"time" binding:"required"` // epoch time in seconds
Host string `json:"host" binding:"required"` // hostname
Source string `json:"source" binding:"required"` // app name
SourceType string `json:"sourcetype" binding:"required"` // Splunk bucket to group logs in
Index string `json:"index" binding:"required"` // idk what it does..
Event interface{} `json:"event" binding:"required"` // throw any useful key/val pairs here
}
Event represents the log event object that is sent to Splunk when Client.Log is called.
type Hook ¶
type Hook struct {
Client *Client
// contains filtered or unexported fields
}
Hook is a logrus hook for splunk
type RemoteSplunkError ¶
type RemoteSplunkError struct {
URL string
Status int
ContentType string
ContentLength int64
BodySnippet string
}
func NewRemoteSplunkError ¶
func NewRemoteSplunkError(response *http.Response) *RemoteSplunkError
func (*RemoteSplunkError) Error ¶
func (e *RemoteSplunkError) Error() string
type Writer ¶
type Writer struct {
Client *Client
// How often the write buffer should be flushed to splunk
FlushInterval time.Duration
// How many Write()'s before buffer should be flushed to splunk
FlushThreshold int
// Max number of retries we should do when we flush the buffer
MaxRetries int
// contains filtered or unexported fields
}
Writer is a threadsafe, aysnchronous splunk writer. It implements io.Writer for usage in logging libraries, or whatever you want to send to splunk :) Writer.Client's configuration determines what source, sourcetype & index will be used for events Example for logrus:
splunkWriter := &splunk.Writer {Client: client}
logrus.SetOutput(io.MultiWriter(os.Stdout, splunkWriter))
Source Files