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)
Incoming requests can contain a header which indicates that a trace is being performed for the corresponding operation. The SpanFromRequest function will look for this header in an *http.Request. If it is present, SpanFromRequest creates a span for the request; otherwise it returns nil.
func handler(w http.ResponseWriter, r *http.Request) {
span := traceClient.SpanFromRequest(r)
defer span.Finish()
...
}
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()
...
}
Client.SpanFromRequest returns a nil *Span if there is no trace header in the request. All of the exported functions on *Span do nothing when the *Span is nil, so you do not need to guard against nil receivers yourself.
SpanFromRequest also returns nil if the *Client is nil, so you can disable tracing by not initializing your *Client variable.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var EnableGRPCTracing option.ClientOption = option.WithGRPCDialOption(EnableGRPCTracingDialOption)
EnableGRPCTracing enables tracing of requests for clients that use gRPC connections. The functionality in gRPC that this relies on is currently experimental.
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 ¶
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 (*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 ¶
SpanFromRequest returns a new trace span. If the incoming HTTP request's headers don't specify that the request should be traced, and the sampling policy doesn't determine the request should be traced, the returned span will be nil. It also returns nil if the client is nil. When Finish is called on the returned span, the span and its descendants are uploaded to the Google Stackdriver Trace server.
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 SamplingPolicy ¶ added in v0.2.0
type SamplingPolicy interface {
// Sample determines whether to sample the next request. If so, it also
// returns a string and rate describing the reason the request was chosen.
Sample() (sample bool, policy string, rate float64)
}
func NewLimitedSampler ¶ added in v0.2.0
func NewLimitedSampler(fraction, maxqps float64) (SamplingPolicy, error)
NewLimitedSampler returns a sampling policy that traces a given fraction of requests, and enforces a limit on the number of traces per second. Returns a nil SamplingPolicy if either fraction or maxqps is zero.
type Span ¶
type Span struct {
// contains filtered or unexported fields
}
Span contains information about one span of a trace.
func FromContext ¶
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 ¶
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 ¶
NewRemoteChild creates a new span as a child of s. Span details are set from an outgoing *http.Request r. A header is set in r so that the trace context is propagated to the destination. If s is nil, does nothing and returns nil.
Source Files