README
¶
splunk
A Splunk event handler for log/slog. Features:
- Configurable URL, token, source and hostname.
- Batching support.
- Non-blocking flush call support.
- Blocking close call support with a timeout.
- Memory pool for event byte buffers.
- Utilizes JSON handler from the standard library.
- Built for performance (no JSON stdlib encoding). * Statistics for better observability.
How to use
package main
import (
"bytes"
"context"
"fmt"
"log/slog"
"net/http"
"net/http/httptest"
"os"
"github.com/osbuild/logging/pkg/splunk"
)
func main() {
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
buf := new(bytes.Buffer)
buf.ReadFrom(r.Body)
fmt.Println(buf.String())
}))
defer srv.Close()
url, ok := os.LookupEnv("SPLUNK_URL")
if !ok {
url = srv.URL
}
token, ok := os.LookupEnv("SPLUNK_TOKEN")
h := splunk.NewSplunkHandler(context.Background(), slog.LevelDebug, url, token, "source", "hostname")
log := slog.New(h)
log.Debug("message", "k1", "v1")
defer func() {
// block until all logs are sent but not more than 2 seconds
h.Close()
s := h.Statistics()
fmt.Printf("sent %d events in %d batches\n", s.EventCount, s.BatchCount)
}()
}
Run the example against mock Splunk with the following command:
go run github.com/osbuild/logging/internal/example_splunk/
Run the example against real Splunk with the following command:
export SPLUNK_URL=https://xxx.splunkcloud.com/services/collector/event
export SPLUNK_TOKEN=x7d04bb1-7eae-4bde-9d92-89837206239x
go run github.com/osbuild/logging/internal/example_splunk/
Documentation
¶
Overview ¶
A log/slog handler for Splunk event logging.
Index ¶
- Constants
- Variables
- type SplunkConfig
- type SplunkHandler
- func (h *SplunkHandler) Close() error
- func (h *SplunkHandler) CloseWithTimeout(timeout time.Duration) error
- func (h *SplunkHandler) Enabled(ctx context.Context, level slog.Level) bool
- func (h *SplunkHandler) Flush()
- func (h *SplunkHandler) Handle(ctx context.Context, r slog.Record) error
- func (h *SplunkHandler) Statistics() Stats
- func (h *SplunkHandler) WithAttrs(attrs []slog.Attr) slog.Handler
- func (h *SplunkHandler) WithGroup(name string) slog.Handler
- func (h *SplunkHandler) Write(buf []byte) (int, error)
- type Stats
Constants ¶
const ( // DefaultPayloadsChannelSize is the size of the channel that holds payloads, default 4k. DefaultPayloadsChannelSize = 4096 // DefaultEventSize is the initial capacity of the event buffer, default 1kB DefaultEventSize = 1024 // DefaultMaximumSize is the initial capacity of the event buffer before it is flushed, default is 1MB. DefaultMaximumSize = 1024 * 1024 // DefaultSendFrequency is the frequency at which payloads are sent at a maximum, default 5s. DefaultSendFrequency = 5 * time.Second )
const (
// EventKey is the key used to group the event attributes.
EventKey = "event"
)
Variables ¶
var ErrCloseTimeout = errors.New("close timeout reached")
var ErrFullOrClosed = errors.New("cannot create new splunk event: channel full or closed")
ErrFullOrClosed is returned when the payloads channel is full or closed via close().
var ErrInvalidEvent = errors.New("invalid event: must be a JSON object with trailing newline")
ErrInvalidEvent is returned when the event is not a valid JSON object with a trailing newline.
var ErrResponseNotOK = errors.New("unexpected response from Splunk")
ErrResponseNotOK is returned when the response from Splunk is not 200 OK.
Functions ¶
This section is empty.
Types ¶
type SplunkConfig ¶
type SplunkConfig struct {
// Level is the minimum level of logs that will be sent to Splunk.
Level slog.Level
// URL is the Splunk HEC endpoint.
URL string
// Token is the Splunk HEC token.
Token string
// Source is the source of the logs.
Source string
// Hostname is the hostname of the logs.
Hostname string
// DefaultMaximumSize is the initialized capacity of the event buffer before it is flushed, default is 1MB.
DefaultMaximumSize int
}
SplunkConfig is the configuration for the Splunk handler.
type SplunkHandler ¶
type SplunkHandler struct {
// contains filtered or unexported fields
}
SplunkHandler sends records to a Splunk instance as events.
func NewSplunkHandler ¶
func NewSplunkHandler(ctx context.Context, config SplunkConfig) *SplunkHandler
NewSplunkHandler creates a new SplunkHandler. It uses highly-optimized JSON handler from the standard library to format the log records. The handler implements io.Writer interface which is then used to stream JSON data into the Splunk client.
func (*SplunkHandler) Close ¶
func (h *SplunkHandler) Close() error
Close flushes all pending payloads and closes the Splunk client. Sending new logs after closing the handler will return ErrFullOrClosed. The call can block but not longer than 2 seconds. Use CloseWithTimeout to specify a custom timeout.
func (*SplunkHandler) CloseWithTimeout ¶ added in v0.0.5
func (h *SplunkHandler) CloseWithTimeout(timeout time.Duration) error
CloseWithTimeout flushes all pending payloads and closes the Splunk client. Sending new logs after closing the handler will return ErrFullOrClosed. The call can block but not longer than the specified timeout.
Returns ErrCloseTimeout if the timeout was reached.
func (*SplunkHandler) Flush ¶
func (h *SplunkHandler) Flush()
Flush flushes all pending payloads to the Splunk client. This is done automatically and it is not necessary to call this method unless you want to force the flush manually (e.g. in an unit test). Calling this method does not guarantee immediate delivery of the payloads to the Splunk instance.
func (*SplunkHandler) Statistics ¶
func (h *SplunkHandler) Statistics() Stats
Statistics returns the statistics of the Splunk client.
type Stats ¶
type Stats struct {
// Total number of events sent to Splunk
EventCount uint64
// Total number of requests sent to Splunk
BatchCount uint64
// Total number of HTTP retries
RetryCount uint64
// Total number of non-200 HTTP responses
NonHTTP200Count uint64
// Total number of events enqueued (EventsEnqueued <= EventCount)
EventsEnqueued uint64
// Last request duration
LastRequestDuration time.Duration
}
Source Files