client

Documentation

Overview

Package client implements Splunk's HTTP Event Collector (EC) client.

Index

• type Client
  • func NewClient(c Configuration) (Client, error)
  • func (cli *Client) Configure(proto string, host string, port int) error
  • func (cli *Client) HealthCheck() error
  • func (cli *Client) Send(evt Event) error
• type Configuration
  • func NewConfiguration(f string) (Configuration, error)
• type Event
• type EventResponse
• type HealthCheckResponse

Types

type Client

type Client struct {
	Name      string
	Endpoints struct {
		Health string
		Event  string
		Raw    string
	}
	Token string
	// contains filtered or unexported fields
}

Client is a Splunk HEC client. It sends messages to Splunk's RESTful API using HTTP/S transport.

The Client uses HEC Tokens to authenticate to the API.

func NewClient

func NewClient(c Configuration) (Client, error)

NewClient initiates an instance of a Client based on the Configuration provided. The function populates URL for various endpoints, e.g. health, event, etc. Lastly, the function performs a health check to assess whether HEC interfaces is available. Upon successful completion of the health chech, the function returns an instance of the Client.

func (*Client) Configure

func (cli *Client) Configure(proto string, host string, port int) error

Configure function populates URL for various endpoints, e.g. health, event, etc.

func (*Client) HealthCheck

func (cli *Client) HealthCheck() error

HealthCheck performs a health check according to Splunk's REST API specification at http://docs.splunk.com/Documentation/Splunk/7.1.2/RESTREF/RESTinput#services.2Fcollector.2Fhealth.

func (*Client) Send

func (cli *Client) Send(evt Event) error

Send function sends events to HTTP Event Collector using the Splunk platform JSON event protocol. The interface is described at http://docs.splunk.com/Documentation/Splunk/7.1.2/RESTREF/RESTinput#services.2Fcollector

type Configuration

type Configuration struct {
	LogLevel  log.Level `json:"log_level" yaml:"log_level"`
	File      string    `json:"conf_file" yaml:"conf_file"`
	Collector struct {
		Proto   string `json:"proto" yaml:"proto"`
		Host    string `json:"host" yaml:"host"`
		Port    int    `json:"port" yaml:"port"`
		Token   string `json:"token" yaml:"token"`
		Timeout int
	}
}

Configuration is a configuration for the Client. It allows specifying host and port of a Splunk HEC endpoint, as well as HEC token.

func NewConfiguration

func NewConfiguration(f string) (Configuration, error)

NewConfiguration creates an instance of a Configuration from the configuration file in YAML format on a local filesystem.

type Event

type Event struct {
	Channel    string            `json:"channel,omitempty" yaml:"channel"`
	Message    string            `json:"event" yaml:"event"`
	Fields     map[string]string `json:"fields,omitempty" yaml:"fields"`
	Host       string            `json:"host,omitempty" yaml:"host"`
	Index      string            `json:"index,omitempty" yaml:"index"`
	Source     string            `json:"source,omitempty" yaml:"source"`
	SourceType string            `json:"sourcetype,omitempty" yaml:"sourcetype"`
	Time       uint64            `json:"time,omitempty" yaml:"time"`
}

Event represents an event sent to HTTP Event Collector. It conforms to the standard described in `services/collector` REST API documentation at http://docs.splunk.com/Documentation/Splunk/7.1.2/RESTREF/RESTinput#services.2Fcollector

type EventResponse

type EventResponse struct {
	Text         string `json:"text" yaml:"text"`
	Code         int    `json:"code" yaml:"code"`
	InvalidEvent int    `json:"invalid-event-number" yaml:"invalid-event-number"`
	AckID        int    `json:"ackId" yaml:"ackId"`
}

EventResponse is the response payload of an event submission to HEC endpoint. The response ordinarily contains the following fields:

• Text: Human readable status, same value as code.
• Code: Machine format status, same value as text.
• InvalidEvent: This field gets populated when errors occur. It indicates the zero-based index of first invalid event in an event sequence.
• AckID: This field gets populated when "useACK" is enabled for a token. It indicates the "ackId" to use for checking an indexer acknowledgement.

The following helps understanding the meaning of the values of the Code field:

• 0: "200 OK", Success
• 1: "403 Forbidden", Token disabled
• 2: "401 Unauthorized", Token is required
• 3: "401 Unauthorized", Invalid authorization
• 4: "403 Forbidden", Invalid token
• 5: "400 Bad Request", No data
• 6: "400 Bad Request", Invalid data format
• 7: "400 Bad Request", Incorrect index
• 8: "500 Internal Error", Internal server error
• 9: "503 Service Unavailable", Server is busy
• 10: "400 Bad Request", Data channel is missing
• 11: "400 Bad Request", Invalid data channel
• 12: "400 Bad Request", Event field is required
• 13: "400 Bad Request", Event field cannot be blank
• 14: "400 Bad Request", ACK is disabled
• 15: "400 Bad Request", Error in handling indexed fields
• 16: "400 Bad Request", Query string authorization is not enabled

type HealthCheckResponse

type HealthCheckResponse struct {
	Code int    `json:"code" yaml:"code"`
	Text string `json:"text" yaml:"text"`
}

HealthCheckResponse is the response payload of a health check. It checks whether there is space available in the queue. Per the specification, the value of Code field of HealthCheckResponse has the following meaning:

• 200: HEC is available and accepting input
• 400: Invalid HEC token
• 503: HEC is unhealthy, queues are full