beeline-go: github.com/honeycombio/beeline-go Index | Files | Directories

package beeline

import "github.com/honeycombio/beeline-go"

Package beeline aids adding instrumentation to go apps using Honeycomb.

Summary

This package and its subpackages contain bits of code to use to make your life easier when instrumenting a Go app to send events to Honeycomb. Most applications will use something out of the `wrappers` package and the `beeline` package.

The `beeline` package provides the entry point - initialization and the basic method to add fields to events.

The `trace` package offers more direct control over the generated events and how they connect together to form traces. It can be used if you need more functionality (eg asynchronous spans, other field naming standards, trace propagation).

The `propagation`, `sample`, and `timer` packages are used internally and not very interesting.

The `wrappers` package contains middleware to use with other existing packages such as HTTP routers (eg goji, gorilla, or just plain net/http) and SQL packages (including sqlx and pop).

Finally the `examples` package contains small example applications that use the various wrappers and the beeline.

Regardless of which subpackages are used, there is a small amount of global configuration to add to your application's startup process. At the bare minimum, you must pass in your team write key and identify a dataset name to authorize your code to send events to Honeycomb and tell it where to send events.

func main() {
  beeline.Init(beeline.Config{
    WriteKey: "abcabc123123defdef456456",
    Dataset: "myapp",
  })
  ...

Once configured, use one of the subpackages to wrap HTTP handlers and SQL db objects.

Examples

There are runnable examples at https://github.com/honeycombio/beeline-go/tree/master/examples and examples of each wrapper in the godoc.

The most complete example is in `nethttp`; it covers - beeline initialization - using the net/http wrapper - creating additional spans for larger chunks of work - wrapping an outbound http call - modifying spans on the way out to scrub information - a custom sampling method

TODO create two comprehensive examples, one showing basic beeline use and the other the more exciting things you can do with direct access to the trace and span objects.

Index

Package Files

beeline.go doc.go version.go

func AddField Uses

func AddField(ctx context.Context, key string, val interface{})

AddField allows you to add a single field to an event anywhere downstream of an instrumented request. After adding the appropriate middleware or wrapping a Handler, feel free to call AddField freely within your code. Pass it the context from the request (`r.Context()`) and the key and value you wish to add.This function is good for span-level data, eg timers or the arguments to a specific function call, etc. Fields added here are prefixed with `app.`

func AddFieldToTrace Uses

func AddFieldToTrace(ctx context.Context, key string, val interface{})

AddFieldToTrace adds the field to both the currently active span and all other spans involved in this trace that occur within this process. Additionally, these fields are packaged up and passed along to downstream processes if they are also using a beeline. This function is good for adding context that is better scoped to the request than this specific unit of work, eg user IDs, globally relevant feature flags, errors, etc. Fields added here are prefixed with `app.`

func Close Uses

func Close()

Close shuts down the beeline. Closing does not send any pending traces but does flush any pending libhoney events and blocks until they have been sent. It is optional to close the beeline, and prohibited to try and send an event after the beeline has been closed.

func Flush Uses

func Flush(ctx context.Context)

Flush sends any pending events to Honeycomb. This is optional; events will be flushed on a timer otherwise. It is useful to flush before AWS Lambda functions finish to ensure events get sent before AWS freezes the function. Flush implicitly ends all currently active spans.

func Init Uses

func Init(config Config)

Init intializes the honeycomb instrumentation library.

func StartSpan Uses

func StartSpan(ctx context.Context, name string) (context.Context, *trace.Span)

StartSpan lets you start a new span as a child of an already instrumented handler. If there isn't an existing wrapped handler in the context when this is called, it will start a new trace. Spans automatically get a `duration_ms` field when they are ended; you should not explicitly set the duration. The name argument will be the primary way the span is identified in the trace view within Honeycomb. You get back a fresh context with the new span in it as well as the actual span that was just created. You should call `span.Send()` when the span should be sent (often in a defer immediately after creation). You should pass the returned context downstream.

type Config Uses

type Config struct {
    // Writekey is your Honeycomb authentication token, available from
    // https://ui.honeycomb.io/account. default: apikey-placeholder
    WriteKey string
    // Dataset is the name of the Honeycomb dataset to which events will be
    // sent. default: beeline-go
    Dataset string
    // Service Name identifies your application. While optional, setting this
    // field is extremely valuable when you instrument multiple services. If set
    // it will be added to all events as `service_name`
    ServiceName string
    // SamplRate is a positive integer indicating the rate at which to sample
    // events. Default sampling is at the trace level - entire traces will be
    // kept or dropped. default: 1 (meaning no sampling)
    SampleRate uint
    // SamplerHook is a function that will get run with the contents of each
    // event just before sending the event to Honeycomb. Register a function
    // with this config option to have manual control over sampling within the
    // beeline. The function should return true if the event should be kept and
    // false if it should be dropped.  If it should be kept, the returned
    // integer is the sample rate that has been applied. The SamplerHook
    // overrides the default sampler. Runs before the PresendHook.
    SamplerHook func(map[string]interface{}) (bool, int)
    // PresendHook is a function call that will get run with the contents of
    // each event just before sending them to Honeycomb. The function registered
    // here may mutate the map passed in to add, change, or drop fields from the
    // event before it gets sent to Honeycomb. Does not get invoked if the event
    // is going to be dropped because of sampling. Runs after the SamplerHook.
    PresendHook func(map[string]interface{})

    // APIHost is the hostname for the Honeycomb API server to which to send
    // this event. default: https://api.honeycomb.io/
    // Not used if client is set
    APIHost string
    // STDOUT when set to true will print events to STDOUT *instead* of sending
    // them to honeycomb; useful for development. default: false
    // Not used if client is set
    STDOUT bool
    // Mute when set to true will disable Honeycomb entirely; useful for tests
    // and CI. default: false
    // Not used if client is set
    Mute bool
    // Debug will emit verbose logging to STDOUT when true. If you're having
    // trouble getting the beeline to work, set this to true in a dev
    // environment.
    Debug bool
    // MaxBatchSize, if set, will override the default number of events
    // (libhoney.DefaultMaxBatchSize) that are sent per batch.
    // Not used if client is set
    MaxBatchSize uint
    // BatchTimeout, if set, will override the default time (libhoney.DefaultBatchTimeout)
    // for sending batches that have not been fully-filled.
    // Not used if client is set
    BatchTimeout time.Duration
    // MaxConcurrentBatches, if set, will override the default number of
    // goroutines (libhoney.DefaultMaxConcurrentBatches) that are used to send batches of events in parallel.
    // Not used if client is set
    MaxConcurrentBatches uint
    // PendingWorkCapacity overrides the default event queue size (libhoney.DefaultPendingWorkCapacity).
    // If the queue is full, events will be dropped.
    // Not used if client is set
    PendingWorkCapacity uint

    // Client, if specified, allows overriding the default client used to send events to Honeycomb
    // If set, overrides many fields in this config - see descriptions
    Client *libhoney.Client
}

Config is the place where you configure your Honeycomb write key and dataset name. WriteKey is the only required field in order to actually send events to Honeycomb.

Directories

PathSynopsis
clientPackage client is used to store the state of the libhoney client that sends all beeline events, and provides wrappers of libhoney API functions that are safe to use even if the client is not initialized.
examples/echo_ex
examples/goji
examples/gorilla
examples/http_and_sql
examples/httprouter
examples/nethttp
examples/nethttpfunc
examples/pop
propagation
sample
timerPackage timer is a small convenience package for timing blocks of code.
tracePackage trace gives access to direct control over the span and trace objects used by the beeline.
wrappers/common
wrappers/hnyechoPackage hnyecho has middleware to use with the Echo router.
wrappers/hnygojiPackage hnygoji has Middleware to use with the Goji muxer.
wrappers/hnygorillaPackage hnygorilla has Middleware to use with the Gorilla muxer.
wrappers/hnyhttprouterPackage hnyhttprouter has Middleware to use with the httprouter muxer.
wrappers/hnynethttpPackage hnynethttp provides Honeycomb wrappers for net/http Handlers.
wrappers/hnypopPackage hnypop wraps the gobuffalo/pop ORM.
wrappers/hnysqlPackage hnysql wraps `database.sql` to emit one Honeycomb event per DB call.
wrappers/hnysqlxPackage hnysqlx wraps `jmoiron/sqlx` to emit one Honeycomb event per DB call.

Package beeline imports 9 packages (graph) and is imported by 11 packages. Updated 2019-11-07. Refresh now. Tools for package owners.