stackdriver

package module
v0.0.0-...-44c2e4b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 25, 2017 License: Apache-2.0 Imports: 18 Imported by: 0

README

stackdriver

GoDoc

stackdriver is an opentracing implementation that provides support for Stackdriver Trace, Stackdriver Logging, and Stackdriver Error Reporting

Getting Started

To install stackdriver, use:

go get -u github.com/savaki/stackdriver

Sample

Assuming a credentials file, credentials.json, the following can be used:

package main

import (
	"context"
	"time"

	"github.com/opentracing/opentracing-go"
	"github.com/opentracing/opentracing-go/log"
	"github.com/savaki/stackdriver"
	"google.golang.org/api/option"
)

func main() {
	ctx := context.Background()
	projectID := "your-gcp-project-id"
	tracer, _ := stackdriver.All(ctx, projectID, "service-name", "version",
		option.WithCredentialsFile("credentials.json"),
	)

	opentracing.SetGlobalTracer(tracer)

	span := opentracing.StartSpan("Sample")
	span.LogFields(log.String("message", "recorded to Stackdriver logging"))
	defer span.Finish()

	// stackdriver publishes content asynchronous, need to give it a moment 
	time.Sleep(time.Second * 3) 
}
To Do
  • Implement Span.FinishWithOptions
  • Implement Span.LogKV

Documentation

Index

Constants

View Source 
const (
	TagHttpStatusCode = "http.status_code"
	TagGoogleTraceID  = "appengine.googleapis.com/trace_id"
)

Variables

View Source 
var (
	// Nop tracer that does absolutely nothing beyond implementing opentracing.Tracer
	Nop opentracing.Tracer
)

Functions

func Errorf 

func Errorf(span opentracing.Span, cause error, format string, args ...interface{}) (err error)

Errorf reports and error to the error framework

Types

type Builder 

type Builder struct {
	// contains filtered or unexported fields
}

Builder implements a fluent build to construct a stackdriver Tracer

func NewBuilder 

func NewBuilder() *Builder

NewBuilder constructs a new fluent builder

func (*Builder) Build 

func (b *Builder) Build() (*Tracer, error)

Build constructs the Tracer with the options provided

func (*Builder) ErrorClient 

func (b *Builder) ErrorClient(client *errorreporting.Client) *Builder

ErrorClient specifies the *errorreporting.Client to use

func (*Builder) GCP 

func (b *Builder) GCP(ctx context.Context, projectID, serviceName, serviceVersion string, opts ...option.ClientOption) *Builder

GCP provides a utility that registers the GCP trace, error, and logging clients

func (*Builder) LoggerFunc 

func (b *Builder) LoggerFunc(fn LoggerFunc) *Builder

LoggerFuncs appends to the list of loggers the Tracer will output to

func (*Builder) Loggers 

func (b *Builder) Loggers(loggers ...Logger) *Builder

Loggers appends to the list of loggers the Tracer will output to

func (*Builder) SetBaggageItem 

func (b *Builder) SetBaggageItem(key, value string) *Builder

SetBaggageItem specifies root baggage that will be propagated to all spans

func (*Builder) TraceClient 

func (b *Builder) TraceClient(client *trace.Client) *Builder

TraceClient specifies the *trace.Client to use

type Logger 

type Logger interface {
	Log(e logging.Entry)
}

Logger allows the logger to be specified

func MultiLogger 

func MultiLogger(loggers ...Logger) Logger

MultiLogger allows logging messages to be sent to multiple loggers

type LoggerFunc 

type LoggerFunc func(e logging.Entry)

LoggerFunc provides a functional adapter to Logger

func (LoggerFunc) Log 

func (fn LoggerFunc) Log(e logging.Entry)

Log implements Logger

type Option 

type Option interface {
	Apply(*Options)
}

Option defines a functional configuration

func WithBaggage 

func WithBaggage(baggage map[string]string) Option

WithBaggage allows root baggage to be specified that will propagate to all spans

func WithErrorClient 

func WithErrorClient(client *errorreporting.Client) Option

WithErrorClient allows the error client to be optional specified

func WithLogger 

func WithLogger(logger Logger) Option

WithLogger allows the logger to be configured

func WithTraceClient 

func WithTraceClient(client *trace.Client) Option

WithTraceClient allows the trace client to be optional specified

type Options 

type Options struct {
	ErrorClient *errorreporting.Client
	TraceClient *trace.Client
	Logger      Logger
	Baggage     map[string]string
}

Options contains configuration parameters

type Span 

type Span struct {
	// contains filtered or unexported fields
}

Span references a dapper Span

func (*Span) BaggageItem 

func (s *Span) BaggageItem(restrictedKey string) string

Gets the value for a baggage item given its key. Returns the empty string if the value isn't found in this *Span.

func (*Span) Context 

func (s *Span) Context() opentracing.SpanContext

Context() yields the SpanContext for this *Span. Note that the return value of Context() is still valid after a call to Span.Finish(), as is a call to Span.Context() after a call to Span.Finish().

func (*Span) Finish 

func (s *Span) Finish()

Sets the end timestamp and finalizes *Span state.

With the exception of calls to Context() (which are always allowed), Finish() must be the last call made to any span instance, and to do otherwise leads to undefined behavior.

func (*Span) FinishWithOptions 

func (s *Span) FinishWithOptions(opts opentracing.FinishOptions)

FinishWithOptions is like Finish() but with explicit control over timestamps and log data.

func (*Span) ForeachBaggageItem 

func (s *Span) ForeachBaggageItem(handler func(k, v string) bool)

ForeachBaggageItem implements SpanContext

func (*Span) Log deprecated 

func (s *Span) Log(data opentracing.LogData)

Deprecated: use LogFields or LogKV

func (*Span) LogEvent deprecated 

func (s *Span) LogEvent(event string)

Deprecated: use LogFields or LogKV

func (*Span) LogEventWithPayload deprecated 

func (s *Span) LogEventWithPayload(event string, payload interface{})

Deprecated: use LogFields or LogKV

func (*Span) LogFields 

func (s *Span) LogFields(fields ...log.Field)

LogFields is an efficient and type-checked way to record key:value logging data about a Span, though the programming interface is a little more verbose than LogKV(). Here's an example: 

span.LogFields(
    log.String("event", "soft error"),
    log.String("type", "cache timeout"),
    log.Int("waited.millis", 1500))

Also see Span.FinishWithOptions() and FinishOptions.BulkLogData.

func (*Span) LogKV 

func (s *Span) LogKV(alternatingKeyValues ...interface{})

LogKV is a concise, readable way to record key:value logging data about a Span, though unfortunately this also makes it less efficient and less type-safe than LogFields(). Here's an example: 

span.LogKV(
    "event", "soft error",
    "type", "cache timeout",
    "waited.millis", 1500)

For LogKV (as opposed to LogFields()), the parameters must appear as key-value pairs, like 

span.LogKV(key1, val1, key2, val2, key3, val3, ...)

The keys must all be strings. The values may be strings, numeric types, bools, Go error instances, or arbitrary structs.

(Note to implementors: consider the log.InterleavedKVToFields() helper)

func (*Span) SetBaggageItem 

func (s *Span) SetBaggageItem(restrictedKey, value string) opentracing.Span

SetBaggageItem sets a key:value pair on this *Span and its *SpanContext that also propagates to descendants of this *Span.

SetBaggageItem() enables powerful functionality given a full-stack opentracing integration (e.g., arbitrary application data from a mobile app can make it, transparently, all the way into the depths of a storage system), and with it some powerful costs: use this feature with care.

IMPORTANT NOTE #1: SetBaggageItem() will only propagate baggage items to *future* causal descendants of the associated Span.

IMPORTANT NOTE #2: Use this thoughtfully and with care. Every key and value is copied into every local *and remote* child of the associated Span, and that can add up to a lot of network and cpu overhead.

Returns a reference to this *Span for chaining.

func (*Span) SetOperationName 

func (s *Span) SetOperationName(operationName string) opentracing.Span

Sets or changes the operation name.

func (*Span) SetTag 

func (s *Span) SetTag(key string, value interface{}) opentracing.Span

Adds a tag to the span.

If there is a pre-existing tag set for `key`, it is overwritten.

Tag values can be numeric types, strings, or bools. The behavior of other tag value types is undefined at the OpenTracing level. If a tracing system does not know how to handle a particular value type, it may ignore the tag, but shall not panic.

func (*Span) Tracer 

func (s *Span) Tracer() opentracing.Tracer

Provides access to the Tracer that created this *Span.

type Tracer 

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer is a simple, thin interface for Span creation and SpanContext propagation.

func All 

func All(ctx context.Context, projectID, serviceName, serviceVersion string, opts ...option.ClientOption) (*Tracer, error)

All returns a tracer that includes support for Stackdriver Trace, Logging, and Error Reporting

func New 

func New(opts ...Option) *Tracer

New constructs a new stackdriver tracer

func (*Tracer) Extract 

func (t *Tracer) Extract(format interface{}, carrier interface{}) (opentracing.SpanContext, error)

Extract() returns a SpanContext instance given `format` and `carrier`.

OpenTracing defines a common set of `format` values (see BuiltinFormat), and each has an expected carrier type.

Other packages may declare their own `format` values, much like the keys used by `context.Context` (see https://godoc.org/golang.org/x/net/context#WithValue).

Example usage (with StartSpan): 

carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
clientContext, err := tracer.Extract(opentracing.HTTPHeaders, carrier)

// ... assuming the ultimate goal here is to resume the trace with a
// server-side Span:
var serverSpan opentracing.Span
if err == nil {
    span = tracer.StartSpan(
        rpcMethodName, ext.RPCServerOption(clientContext))
} else {
    span = tracer.StartSpan(rpcMethodName)
}

NOTE: All opentracing.Tracer implementations MUST support all BuiltinFormats.

Return values:

  • A successful Extract returns a SpanContext instance and a nil error
  • If there was simply no SpanContext to extract in `carrier`, Extract() returns (nil, opentracing.ErrSpanContextNotFound)
  • If `format` is unsupported or unrecognized, Extract() returns (nil, opentracing.ErrUnsupportedFormat)
  • If there are more fundamental problems with the `carrier` object, Extract() may return opentracing.ErrInvalidCarrier, opentracing.ErrSpanContextCorrupted, or implementation-specific errors.

See Tracer.Inject().

func (*Tracer) HTTPHandler 

func (t *Tracer) HTTPHandler(h http.Handler) http.Handler

func (*Tracer) Inject 

func (t *Tracer) Inject(sm opentracing.SpanContext, format interface{}, carrier interface{}) error

Inject() takes the `sm` SpanContext instance and injects it for propagation within `carrier`. The actual type of `carrier` depends on the value of `format`.

OpenTracing defines a common set of `format` values (see BuiltinFormat), and each has an expected carrier type.

Other packages may declare their own `format` values, much like the keys used by `context.Context` (see https://godoc.org/golang.org/x/net/context#WithValue).

Example usage (sans error handling): 

carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
err := tracer.Inject(
    span.Context(),
    opentracing.HTTPHeaders,
    carrier)

NOTE: All opentracing.Tracer implementations MUST support all BuiltinFormats.

Implementations may return opentracing.ErrUnsupportedFormat if `format` is not supported by (or not known by) the implementation.

Implementations may return opentracing.ErrInvalidCarrier or any other implementation-specific error if the format is supported but injection fails anyway.

See Tracer.Extract().

func (*Tracer) LogFields 

func (t *Tracer) LogFields(fields ...log.Field)

LogFields allows logging outside the scope of a span

func (*Tracer) StartSpan 

func (t *Tracer) StartSpan(operationName string, opts ...opentracing.StartSpanOption) opentracing.Span

Create, start, and return a new Span with the given `operationName` and incorporate the given StartSpanOption `opts`. (Note that `opts` borrows from the "functional options" pattern, per http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis)

A Span with no SpanReference options (e.g., opentracing.ChildOf() or opentracing.FollowsFrom()) becomes the root of its own trace.

Examples: 

var tracer opentracing.Tracer = ...

// The root-span case:
sp := tracer.StartSpan("GetFeed")

// The vanilla child span case:
sp := tracer.StartSpan(
    "GetFeed",
    opentracing.ChildOf(parentSpan.Context()))

// All the bells and whistles:
sp := tracer.StartSpan(
    "GetFeed",
    opentracing.ChildOf(parentSpan.Context()),
    opentracing.Tag{"user_agent", loggedReq.UserAgent},
    opentracing.StartTime(loggedReq.Timestamp),
)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.