top

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.

Imported by 1 package(s)

  1. github.com/tmc/teststackdrivertrace

Imported only in test by 2 package(s)

  1. github.com/Nitecon/gcloud-golang/trace
  2. github.com/tortuoise/gcloud-golang/trace

Imports 8 package(s)

  1. google.golang.org/api/transport
  2. golang.org/x/net/context
  3. golang.org/x/time/rate
  4. google.golang.org/api/option
  5. google.golang.org/api/support/bundler
  6. google.golang.org/api/gensupport
  7. google.golang.org/api/cloudtrace/v1
  8. google.golang.org/grpc

Test imports 6 package(s)

  1. google.golang.org/api/compute/v1
  2. google.golang.org/api/iterator
  3. google.golang.org/genproto/googleapis/datastore/v1
  4. cloud.google.com/go/datastore
  5. cloud.google.com/go/internal/testutil
  6. cloud.google.com/go/storage