obs

README

obs

Fast and buffered stats, logging and tracing in Go.

Installation

go get -u github.com/mixpanel/obs

Abstract

Mixpanel obs provides a unified interface for emitting metrics, logging as well as tracing.

FlightRecorder is the unified interface. Make an instance of flight recorder or use one of the utility methods.

fr := obs.InitGCP(ctx, "my-service", "INFO")

or

fr := NewFlightRecorder("my-service", mr, logger, tracer)

After obtaining a FlightRecorder, for telemetry you must obtain a span.

fs := fr.WithSpan(ctx)

fs.Info("my info log")
fs.Incr("my.counter")

---

Released under the [MIT License](LICENSE).

Documentation

Overview

Example (FormatRPCName)

fmt.Println(formatRPCName("/Company.Service/Method"))

Output:

Service.Method

Index

• Variables
• func InitCli(ctx context.Context, name, logLevel string) (FlightRecorder, Closer)
• func InitGCP(ctx context.Context, serviceName, logLevel string, opts ...Option) (FlightRecorder, Closer)
• func NewReadCloserWithSpan(ctx context.Context, rc io.ReadCloser, fr FlightRecorder) io.ReadCloser
• func NewWriteCloserWithSpan(ctx context.Context, wc io.WriteCloser, fr FlightRecorder) io.WriteCloser
• func RecordError(receiver metrics.Receiver, err error)
• type Closer
• type DoneFunc
• type FlightRecorder
  • func NewFlightRecorder(name string, metrics metrics.Receiver, logger logging.Logger, ...) FlightRecorder
• type FlightSpan
• type ObsOptions
  • func NewOptions(parser *flags.Parser) *ObsOptions
  • func (opts *ObsOptions) Init(metricsPrefix string)
  • func (opts *ObsOptions) InitLogging()
  • func (opts *ObsOptions) InitWithSink(metricsPrefix string, sink metrics.Sink)
• type Option
  • func SampleRate(n uint64) Option
• type Options
• type Stopwatch
• type Tags
• type Vals
  • func (v Vals) Dupe() Vals
  • func (v Vals) Merge(m Vals) Vals
  • func (v Vals) WithError(err error) Vals

Examples

• Package (FormatRPCName)

Variables

var Log logging.Logger = logging.Null

var Metrics metrics.Receiver = metrics.Null

var NullFR = NullFlightRecorder

var NullFlightRecorder = NewFlightRecorder("null_recorder", metrics.Null, logging.Null, opentracing.NoopTracer{})

var Sink metrics.Sink = metrics.NullSink

Functions

func InitCli

func InitCli(ctx context.Context, name, logLevel string) (FlightRecorder, Closer)

func InitGCP

func InitGCP(ctx context.Context, serviceName, logLevel string, opts ...Option) (FlightRecorder, Closer)

TODO(shimin): InitGCP should be able to set default tags (project, cluster, host) from metadata service. It should also allow the caller to pass in other tags.

func NewReadCloserWithSpan

func NewReadCloserWithSpan(ctx context.Context, rc io.ReadCloser, fr FlightRecorder) io.ReadCloser

NewReadCloserWithSpan wraps an io.ReadCloser, starting the Span when Read is first called and annotating the Trace with the total bytes read when Close is called.

func NewWriteCloserWithSpan

func NewWriteCloserWithSpan(ctx context.Context, wc io.WriteCloser, fr FlightRecorder) io.WriteCloser

NewWriteCloserWithSpan wraps an io.WriteCloser, starting the Span when Write is first called and annotating the Trace with the total bytes written when Close is called.

func RecordError

func RecordError(receiver metrics.Receiver, err error)

Types

type Closer

type Closer func()

type DoneFunc

type DoneFunc func()

type FlightRecorder

type FlightRecorder interface {
	// ScopeName returns a new FlightRecorder that will report telemetry scoped with the provided name.
	ScopeName(name string) FlightRecorder
	// ScopeTags returns a new FlightRecorder that will report telemetry scoped with the provided tags.
	ScopeTags(tags Tags) FlightRecorder
	// Scope returns a new FlightRecorder that will report telemetry scoped with the provided name and tags.
	Scope(name string, tags Tags) FlightRecorder

	// WithNewSpan returns a new FlightSpan to which telemetry can be reported, a context.Context that
	// can be used to propagate this Span, and a DoneFunc that should be called when the caller returns.
	// Latency will be measured automatically by WithNewSpan, with the stop included inside the DoneFunc
	// Typically, you want to use WithNewSpan to group telemetry into discrete meaningful operations, such
	// as service calls.
	WithNewSpan(ctx context.Context, opName string) (FlightSpan, context.Context, DoneFunc)

	// WithSpan returns a FlightSpan that reports into an existing Span that was created with WithNewSpan (or by
	// the underylying tracing system). Typically, you use this function instead of WithNewSpan if the function
	// is doing something minor, or doesn't represent a significant logical chunk of your application.
	WithSpan(ctx context.Context) FlightSpan

	// GRPCClient returns a grpc.DialOption to use to allow this FlightRecorder to intercept and instrument
	// Unary RPCs with that particular client. Make sure to also include GRPCStreamClient.
	GRPCClient() grpc.DialOption

	// GRPCStreamClient returns a grpc.DialOption to use to allow this FlightRecorder to intercept and instrument
	// streaming RPCs with that particular client. Make sure to also include GRPClient.
	GRPCStreamClient() grpc.DialOption

	// GRPCServer returns a grpc.ServerOption to use to allow this FlightRecorder to intercept and instrument
	// unary RPCs with that particular server. Make sure to also include GRPCStreamServer.
	GRPCServer() grpc.ServerOption

	// GRPCStreamServer returns a grpc.ServerOption to use to allow this FlightRecorder to intercept and instrument
	// streaming RPCs with that particular server. Make sure to also include GRPServer.
	GRPCStreamServer() grpc.ServerOption

	// WithNewSpanContext is like WithNewSpan but allows you to specify the parent SpanContext instead of deriving it
	// from the context.Context. This is usually only useful for libraries that derive tracing contexts from out-of-process
	// origins, such as as GRPC request where the tracing context is embeded in GRPC Metadata.
	WithNewSpanContext(ctx context.Context, opName string, spanCtx opentracing.SpanContext) (FlightSpan, context.Context, DoneFunc)

	// WithRootSpan is like WithNewSpan but allows you to force a root span and set its sample rate.
	WithRootSpan(ctx context.Context, opName string, sampleOneInN int) (FlightSpan, context.Context, DoneFunc)

	GetReceiver() metrics.Receiver
}

func NewFlightRecorder

func NewFlightRecorder(name string, metrics metrics.Receiver, logger logging.Logger, tracer opentracing.Tracer) FlightRecorder

NewFlightRecorder constructs a new FlightRecorder with the underlying metrics, logger, and tracer.

type FlightSpan

type FlightSpan interface {
	Trace(message string, vals Vals)
	Debug(message string, vals Vals)
	Info(message string, vals Vals)

	Warn(warnType, message string, vals Vals)
	Critical(critType, message string, vals Vals)

	Incr(name string)
	IncrBy(name string, amount float64)
	AddStat(name string, value float64)
	SetGauge(name string, value float64)

	StartStopwatch(name string) Stopwatch

	TraceSpan() opentracing.Span
	TraceID() (string, bool)
}

type ObsOptions

type ObsOptions struct {
	SyslogLevel     string `long:"syslog.level" default:"NEVER" description:"One of CRIT, ERR, WARN, INFO, DEBUG, NEVER"`
	LogLevel        string `long:"log.level" default:"INFO" description:"One of CRIT, ERR, WARN, INFO, DEBUG, NEVER"`
	LogPath         string `long:"log.path" description:"File path to log. uses stderr if not set"`
	LogFormat       string `long:"log.format" description:"Format of log output" default:"text" choice:"text" choice:"json"`
	MetricsEndpoint string `long:"metrics-endpoint" description:"Address (host:port) to send metrics"`
}

func NewOptions

func NewOptions(parser *flags.Parser) *ObsOptions

func (*ObsOptions) Init

func (opts *ObsOptions) Init(metricsPrefix string)

func (*ObsOptions) InitLogging

func (opts *ObsOptions) InitLogging()

func (*ObsOptions) InitWithSink

func (opts *ObsOptions) InitWithSink(metricsPrefix string, sink metrics.Sink)

InitLogging should already have been invoked

type Option

type Option func(*obsOptions)

var NoTraces Option = func(o *obsOptions) {
	o.tracerOpts.ShouldSample = func(traceID uint64) bool { return false }
}

func SampleRate

func SampleRate(n uint64) Option

SampleRate takes in an int n, and sets the sampling rate of traces to be 1 / n

type Options

type Options struct {
	LogLevel string `long:"obs.log-level" description:"NEVER, DEBUG, INFO, WARN, ERROR or CRITICAL" default:"INFO"`
}

type Stopwatch

type Stopwatch interface {
	Stop()
}

type Tags

type Tags map[string]string

Tags should be used for categorizing telemetry. For example, you should use a Tag for something like query_type but not query_id. Typically the cardinality of values is small.

type Vals

type Vals map[string]interface{}

Vals should be used for providing specific values in telemetry that are specific to that instance of data capture. For example, the specific project_id that a log message pertains to. If the cardinality of possible values is large, then Vals is the right type to use.

func (Vals) Dupe

func (v Vals) Dupe() Vals

func (Vals) Merge

func (v Vals) Merge(m Vals) Vals

func (Vals) WithError

func (v Vals) WithError(err error) Vals