Add a client object to libhoney for isolating traffic

.travis.yml

@@ -4,6 +4,10 @@ dist: trusty
 
 go:
         - 1.6
+        - 1.8
+        - 1.9
+        - "1.10"
+        - 1.11
 
 script:
         - go test ./... -race -v

client.go

@@ -0,0 +1,233 @@
+package libhoney
+
+import (
+	"errors"
+	"sync"
+
+	"github.com/honeycombio/libhoney-go/transmission"
+)
+
+// Client represents an object that can create new builders and events and send
+// them somewhere. It maintains its own sending queue for events, distinct from
+// both the package-level libhoney queue and any other client. Clients should be
+// created with NewClient(config). A manually created Client{} will function as
+// a nil output and drop everything handed to it (so can be safely used in dev
+// and tests). For more complete testing you can create a Client with a
+// MockOutput transmission then inspect the events it would have sent.
+type Client struct {
+	transmission transmission.Sender
+	logger       Logger
+	builder      *Builder
+
+	oneTx      sync.Once
+	oneLogger  sync.Once
+	oneBuilder sync.Once
+}
+
+// ClientConfig is a subset of the global libhoney config that focuses on the
+// configuration of the client itself. The other config options are specific to
+// a given transmission Sender and should be specified there if the defaults
+// need to be overridden.
+type ClientConfig struct {
+	// APIKey is the Honeycomb authentication token. If it is specified during
+	// libhoney initialization, it will be used as the default API key for all
+	// events. If absent, API key must be explicitly set on a builder or
+	// event. Find your team's API keys at https://ui.honeycomb.io/account
+	APIKey string
+
+	// Dataset is the name of the Honeycomb dataset to which to send these events.
+	// If it is specified during libhoney initialization, it will be used as the
+	// default dataset for all events. If absent, dataset must be explicitly set
+	// on a builder or event.
+	Dataset string
+
+	// SampleRate is the rate at which to sample this event. Default is 1,
+	// meaning no sampling. If you want to send one event out of every 250 times
+	// Send() is called, you would specify 250 here.
+	SampleRate uint
+
+	// APIHost is the hostname for the Honeycomb API server to which to send this
+	// event. default: https://api.honeycomb.io/
+	APIHost string
+
+	// Transmission allows you to override what happens to events after you call
+	// Send() on them. By default, events are asynchronously sent to the
+	// Honeycomb API. You can use the MockOutput included in this package in
+	// unit tests, or use the transmission.WriterSender to write events to
+	// STDOUT or to a file when developing locally.
+	Transmission transmission.Sender
+
+	// Logger defaults to nil and the SDK is silent. If you supply a logger here
+	// (or set it to &DefaultLogger{}), some debugging output will be emitted.
+	// Intended for human consumption during development to understand what the
+	// SDK is doing and diagnose trouble emitting events.
+	Logger Logger
+}
+
+// NewClient creates a Client with defaults correctly set
+func NewClient(conf ClientConfig) (*Client, error) {
+	if conf.SampleRate == 0 {
+		conf.SampleRate = defaultSampleRate
+	}
+	if conf.APIHost == "" {
+		conf.APIHost = defaultAPIHost
+	}
+	if conf.Dataset == "" {
+		conf.Dataset = defaultDataset
+	}
+
+	c := &Client{
+		logger: conf.Logger,
+	}
+	c.ensureLogger()
+
+	if conf.Transmission == nil {
+		c.transmission = &transmission.Honeycomb{
+			MaxBatchSize:         DefaultMaxBatchSize,
+			BatchTimeout:         DefaultBatchTimeout,
+			MaxConcurrentBatches: DefaultMaxConcurrentBatches,
+			PendingWorkCapacity:  DefaultPendingWorkCapacity,
+			UserAgentAddition:    UserAgentAddition,
+			Logger:               c.logger,
+			Metrics:              sd,
+		}
+	} else {
+		c.transmission = conf.Transmission
+	}
+	if err := c.transmission.Start(); err != nil {
+		c.logger.Printf("transmission client failed to start: %s", err.Error())
+		return nil, err
+	}
+
+	c.builder = &Builder{
+		WriteKey:   conf.APIKey,
+		Dataset:    conf.Dataset,
+		SampleRate: conf.SampleRate,
+		APIHost:    conf.APIHost,
+		dynFields:  make([]dynamicField, 0, 0),
+		fieldHolder: fieldHolder{
+			data: make(map[string]interface{}),
+		},
+		client: c,
+	}
+
+	return c, nil
+}
+
+func (c *Client) ensureTransmission() {
+	c.oneTx.Do(func() {
+		if c.transmission == nil {
+			c.transmission = &transmission.DiscardSender{}
+			c.transmission.Start()
+		}
+	})
+}
+
+func (c *Client) ensureLogger() {
+	c.oneLogger.Do(func() {
+		if c.logger == nil {
+			c.logger = &nullLogger{}
+		}
+	})
+}
+
+func (c *Client) ensureBuilder() {
+	c.oneBuilder.Do(func() {
+		if c.builder == nil {
+			c.builder = &Builder{
+				dynFields: make([]dynamicField, 0, 0),
+				fieldHolder: fieldHolder{
+					data: make(map[string]interface{}),
+				},
+				client: c,
+			}
+		}
+	})
+}
+
+// Close waits for all in-flight messages to be sent. You should
+// call Close() before app termination.
+func (c *Client) Close() {
+	c.ensureLogger()
+	c.logger.Printf("closing libhoney client")
+	if c.transmission != nil {
+		c.transmission.Stop()
+	}
+}
+
+// Flush closes and reopens the Output interface, ensuring events
+// are sent without waiting on the batch to be sent asyncronously.
+// Generally, it is more efficient to rely on asyncronous batches than to
+// call Flush, but certain scenarios may require Flush if asynchronous sends
+// are not guaranteed to run (i.e. running in AWS Lambda)
+// Flush is not thread safe - use it only when you are sure that no other
+// parts of your program are calling Send
+func (c *Client) Flush() {
+	c.ensureLogger()
+	c.logger.Printf("flushing libhoney client")
+	if c.transmission != nil {
+		c.transmission.Stop()
+		c.transmission.Start()
+	}
+}
+
+// TxResponses returns the channel from which the caller can read the responses
+// to sent events.
+func (c *Client) TxResponses() chan transmission.Response {
+	c.ensureTransmission()
+	return c.transmission.TxResponses()
+}
+
+// AddDynamicField takes a field name and a function that will generate values
+// for that metric. The function is called once every time a NewEvent() is
+// created and added as a field (with name as the key) to the newly created
+// event.
+func (c *Client) AddDynamicField(name string, fn func() interface{}) error {
+	c.ensureTransmission()
+	c.ensureBuilder()
+	return c.builder.AddDynamicField(name, fn)
+}
+
+// AddField adds a Field to the Client's scope. This metric will be inherited by
+// all builders and events.
+func (c *Client) AddField(name string, val interface{}) {
+	c.ensureTransmission()
+	c.ensureBuilder()
+	c.builder.AddField(name, val)
+}
+
+// Add adds its data to the Client's scope. It adds all fields in a struct or
+// all keys in a map as individual Fields. These metrics will be inherited by
+// all builders and events.
+func (c *Client) Add(data interface{}) error {
+	c.ensureTransmission()
+	c.ensureBuilder()
+	return c.builder.Add(data)
+}
+
+// NewEvent creates a new event prepopulated with any Fields present in the
+// Client's scope.
+func (c *Client) NewEvent() *Event {
+	c.ensureTransmission()
+	c.ensureBuilder()
+	return c.builder.NewEvent()
+}
+
+// NewBuilder creates a new event builder. The builder inherits any Dynamic or
+// Static Fields present in the Client's scope.
+func (c *Client) NewBuilder() *Builder {
+	c.ensureTransmission()
+	c.ensureBuilder()
+	return c.builder.Clone()
+}
+
+// sendResponse sends a dropped event response down the response channel
+func (c *Client) sendDroppedResponse(e *Event, message string) {
+	c.ensureTransmission()
+	r := transmission.Response{
+		Err:      errors.New(message),
+		Metadata: e.Metadata,
+	}
+	c.transmission.SendResponse(r)
+
+}