trace

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Nov 30, 2016 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package trace is a Google Stackdriver Trace library.

This package is still experimental and subject to change.

See https://cloud.google.com/trace/api/#data_model for a discussion of traces and spans.

To initialize a client that connects to the Stackdriver Trace server, use the NewClient function. Generally you will want to do this on program initialization.

import "cloud.google.com/go/trace"
...
traceClient, err = trace.NewClient(ctx, projectID)

Calling SpanFromRequest will create a new trace span for an incoming HTTP request. If the request contains a trace context header, it is used to determine the trace ID. Otherwise, a new trace ID is created.

func handler(w http.ResponseWriter, r *http.Request) {
  span := traceClient.SpanFromRequest(r)
  defer span.Finish()
  ...
}

SpanFromRequest returns nil if the *Client is nil, so you can disable tracing by not initializing your *Client variable. All of the exported functions on *Span do nothing when the *Span is nil.

Although a trace span object is created for every request, only a subset of traces are uploaded to the server, for efficiency. By default, the requests that are traced are those with the tracing bit set in the options field of the trace context header. Ideally, you should override this behaviour by calling SetSamplingPolicy. NewLimitedSampler returns an implementation of SamplingPolicy which traces requests that have the tracing bit set, and also randomly traces a specified fraction of requests. Additionally, it sets a limit on the number of requests traced per second. The following example traces one in every thousand requests, up to a limit of 5 per second.

traceClient.SetSamplingPolicy(trace.NewLimitedSampler(0.001, 5))

You can create a new span as a child of an existing span with NewChild.

childSpan := span.NewChild(name)
...
childSpan.Finish()

When sending an HTTP request to another server, NewRemoteChild will create a span to represent the time the current program waits for the request to complete, and attach a header to the outgoing request so that the trace will be propagated to the destination server.

childSpan := span.NewRemoteChild(&httpRequest)
...
childSpan.Finish()

Spans can contain a map from keys to values that have useful information about the span. The elements of this map are called labels. Some labels, whose keys all begin with the string "trace.cloud.google.com/", are set automatically in the following ways:

  • SpanFromRequest sets some labels to data about the incoming request.
  • NewRemoteChild sets some labels to data about the outgoing request.
  • Finish sets a label to a stack trace, if the stack trace option is enabled in the incoming trace header.
  • The WithResponse option sets some labels to data about a response.

You can also set labels using SetLabel. If a label is given a value automatically and by SetLabel, the automatically-set value is used.

span.SetLabel(key, value)

The WithResponse option can be used when Finish is called.

childSpan := span.NewRemoteChild(outgoingReq)
resp, err := http.DefaultClient.Do(outgoingReq)
...
childSpan.Finish(trace.WithResponse(resp))

When a span created by SpanFromRequest is finished, the finished spans in the corresponding trace -- the span itself and its descendants -- are uploaded to the Stackdriver Trace server using the *Client that created the span. Finish returns immediately, and uploading occurs asynchronously. You can use the FinishWait function instead to wait until uploading has finished.

err := span.FinishWait()

Using contexts to pass *trace.Span objects through your program will often be a better approach than passing them around explicitly. This allows trace spans, and other request-scoped or part-of-request-scoped values, to be easily passed through API boundaries. Various Google Cloud libraries will retrieve trace spans from contexts and automatically create child spans for API requests. See https://blog.golang.org/context for more discussion of contexts. A derived context containing a trace span can be created using NewContext.

span := traceClient.SpanFromRequest(r)
ctx = trace.NewContext(ctx, span)

The span can be retrieved from a context elsewhere in the program using FromContext.

func foo(ctx context.Context) {
  newSpan := trace.FromContext(ctx).NewChild("in foo")
  defer newSpan.Finish()
  ...
}

Index

Constants

This section is empty.

Variables

EnableGRPCTracing enables tracing of requests for clients that use gRPC connections. The functionality in gRPC that this relies on is currently experimental.

View Source
var EnableGRPCTracingDialOption grpc.DialOption = grpc.WithUnaryInterceptor(grpc.UnaryClientInterceptor(grpcUnaryInterceptor))

EnableGRPCTracingDialOption enables tracing of requests that are sent over a gRPC connection. The functionality in gRPC that this relies on is currently experimental.

Functions

func NewContext

func NewContext(ctx context.Context, s *Span) context.Context

NewContext returns a derived context containing the span.

Types

type Client

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

Client is a client for uploading traces to the Google Stackdriver Trace server.

func NewClient

func NewClient(ctx context.Context, projectID string, opts ...option.ClientOption) (*Client, error)

NewClient creates a new Google Stackdriver Trace client.

func (*Client) SetSamplingPolicy added in v0.2.0

func (c *Client) SetSamplingPolicy(p SamplingPolicy)

SetSamplingPolicy sets the SamplingPolicy that determines how often traces are initiated by this client.

func (*Client) SpanFromRequest

func (client *Client) SpanFromRequest(r *http.Request) *Span

SpanFromRequest returns a new trace span.

It returns nil iff the client is nil.

If the incoming HTTP request contains a trace context header, the trace ID, parent span ID, and tracing options will be read from that header. Otherwise, a new trace ID is made and the parent span ID is zero.

If a non-nil sampling policy has been set in the client, it can override the options set in the header and choose whether to trace the request.

If the request is not being traced, then a *Span is returned anyway, but it will not be uploaded to the server -- it is only useful for propagating trace context to child requests and for getting the TraceID. All its methods can still be called -- the Finish, FinishWait, and SetLabel methods do nothing. NewChild does nothing, and returns the same *Span. TraceID works as usual.

type Decision added in v0.4.0

type Decision struct {
	Trace  bool    // Whether to trace the request.
	Sample bool    // Whether the trace is included in the random sample.
	Policy string  // Name of the sampling policy.
	Weight float64 // Sample weight to be used in statistical calculations.
}

Decision is the value returned by a call to a SamplingPolicy's Sample method.

type FinishOption

type FinishOption interface {
	// contains filtered or unexported methods
}

func WithResponse

func WithResponse(resp *http.Response) FinishOption

WithResponse returns an option that can be passed to Finish that indicates that some labels for the span should be set using the given *http.Response.

type Parameters added in v0.4.0

type Parameters struct {
	HasTraceHeader bool // whether the incoming request has a valid X-Cloud-Trace-Context header.
}

Parameters contains the values passed to a SamplingPolicy's Sample method.

type SamplingPolicy added in v0.2.0

type SamplingPolicy interface {
	// Sample returns a Decision.
	// If Trace is false in the returned Decision, then the Decision should be
	// the zero value.
	Sample(p Parameters) Decision
}

func NewLimitedSampler added in v0.2.0

func NewLimitedSampler(fraction, maxqps float64) (SamplingPolicy, error)

NewLimitedSampler returns a sampling policy that randomly samples a given fraction of requests. It also enforces a limit on the number of traces per second. It tries to trace every request with a trace header, but will not exceed the qps limit to do it.

type Span

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

Span contains information about one span of a trace.

func FromContext

func FromContext(ctx context.Context) *Span

FromContext returns the span contained in the context, or nil.

func (*Span) Finish

func (s *Span) Finish(opts ...FinishOption)

Finish declares that the span has finished.

If s is nil, Finish does nothing and returns nil.

If the option trace.WithResponse(resp) is passed, then some labels are set for s using information in the given *http.Response. This is useful when the span is for an outgoing http request; s will typically have been created by NewRemoteChild in this case.

If s is a root span (one created by SpanFromRequest) then s, and all its descendant spans that have finished, are uploaded to the Google Stackdriver Trace server asynchronously.

func (*Span) FinishWait

func (s *Span) FinishWait(opts ...FinishOption) error

FinishWait is like Finish, but if s is a root span, it waits until uploading is finished, then returns an error if one occurred.

func (*Span) NewChild

func (s *Span) NewChild(name string) *Span

NewChild creates a new span with the given name as a child of s. If s is nil, does nothing and returns nil.

func (*Span) NewRemoteChild

func (s *Span) NewRemoteChild(r *http.Request) *Span

NewRemoteChild creates a new span as a child of s.

Some labels in the span are set from the outgoing *http.Request r.

A header is set in r so that the trace context is propagated to the destination. The parent span ID in that header is set as follows:

  • If the request is being traced, then the ID of s is used.
  • If the request is not being traced, but there was a trace context header in the incoming request for this trace (the request passed to SpanFromRequest), the parent span ID in that header is used.
  • Otherwise, the parent span ID is zero.

The tracing bit in the options is set if tracing is enabled, or if it was set in the incoming request.

If s is nil, does nothing and returns nil.

func (*Span) SetLabel

func (s *Span) SetLabel(key, value string)

SetLabel sets the label for the given key to the given value. If the value is empty, the label for that key is deleted. If a label is given a value automatically and by SetLabel, the automatically-set value is used. If s is nil, does nothing.

func (*Span) TraceID added in v0.2.0

func (s *Span) TraceID() string

TraceID returns the ID of the trace to which s belongs.

Directories

Path Synopsis
Package trace is an experimental, auto-generated package for the trace API.
Package trace is an experimental, auto-generated package for the trace API.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL