trace

Documentation

Overview

Package trace is OBSOLETE. See https://cloud.google.com/trace/docs/setup/go.

Index

• Constants
• func NewContext(ctx context.Context, s *Span) context.Context
• type Client
  • func NewClient(ctx context.Context, projectID string, opts ...option.ClientOption) (*Client, error)
  • func (c *Client) GRPCClientInterceptor() grpc.UnaryClientInterceptor
  • func (c *Client) GRPCServerInterceptor() grpc.UnaryServerInterceptor
  • func (c *Client) HTTPHandler(h http.Handler) http.Handler
  • func (c *Client) NewSpan(name string) *Span
  • func (c *Client) SetSamplingPolicy(p SamplingPolicy)
  • func (c *Client) SpanFromHeader(name string, header string) *Span
  • func (c *Client) SpanFromRequest(r *http.Request) *Span
• type Decision
• type FinishOption
  • func WithResponse(resp *http.Response) FinishOption
• type Parameters
• type SamplingPolicy
  • func NewLimitedSampler(fraction, maxqps float64) (SamplingPolicy, error)
• type Span
  • func FromContext(ctx context.Context) *Span
  • func (s *Span) Finish(opts ...FinishOption)
  • func (s *Span) FinishWait(opts ...FinishOption) error
  • func (s *Span) Header() string
  • func (s *Span) NewChild(name string) *Span
  • func (s *Span) NewRemoteChild(r *http.Request) *Span
  • func (s *Span) SetLabel(key, value string)
  • func (s *Span) TraceID() string
  • func (s *Span) Traced() bool
• type Transport
  • func (t Transport) CancelRequest(req *http.Request)
  • func (t Transport) RoundTrip(req *http.Request) (*http.Response, error)

Examples

• Client.HTTPHandler

Constants

const (
	LabelComponent          = `trace.cloud.google.com/component`
	LabelErrorMessage       = `trace.cloud.google.com/error/message`
	LabelErrorName          = `trace.cloud.google.com/error/name`
	LabelHTTPClientCity     = `trace.cloud.google.com/http/client_city`
	LabelHTTPClientCountry  = `trace.cloud.google.com/http/client_country`
	LabelHTTPClientProtocol = `trace.cloud.google.com/http/client_protocol`
	LabelHTTPClientRegion   = `trace.cloud.google.com/http/client_region`
	LabelHTTPHost           = `trace.cloud.google.com/http/host`
	LabelHTTPMethod         = `trace.cloud.google.com/http/method`
	LabelHTTPRedirectedURL  = `trace.cloud.google.com/http/redirected_url`
	LabelHTTPRequestSize    = `trace.cloud.google.com/http/request/size`
	LabelHTTPResponseSize   = `trace.cloud.google.com/http/response/size`
	LabelHTTPStatusCode     = `trace.cloud.google.com/http/status_code`
	LabelHTTPURL            = `trace.cloud.google.com/http/url`
	LabelHTTPUserAgent      = `trace.cloud.google.com/http/user_agent`
	LabelPID                = `trace.cloud.google.com/pid`
	LabelSamplingPolicy     = `trace.cloud.google.com/sampling_policy`
	LabelSamplingWeight     = `trace.cloud.google.com/sampling_weight`
	LabelStackTrace         = `trace.cloud.google.com/stacktrace`
	LabelTID                = `trace.cloud.google.com/tid`
)

Stackdriver Trace API predefined labels.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

const (
	// ScopeTraceAppend grants permissions to write trace data for a project.
	//
	// Deprecated: see https://cloud.google.com/trace/docs/setup/go.
	ScopeTraceAppend = "https://www.googleapis.com/auth/trace.append"

	// ScopeCloudPlatform grants permissions to view and manage your data
	// across Google Cloud Platform services.
	//
	// Deprecated: see https://cloud.google.com/trace/docs/setup/go.
	ScopeCloudPlatform = "https://www.googleapis.com/auth/cloud-platform"
)

Functions

func NewContext

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

NewContext returns a derived context containing the span.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

Types

type Client

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

Client is a client for uploading traces to the Google Stackdriver Trace service. A nil Client will no-op for all of its methods.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func NewClient

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

NewClient creates a new Google Stackdriver Trace client.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Client) GRPCClientInterceptor

func (c *Client) GRPCClientInterceptor() grpc.UnaryClientInterceptor

GRPCClientInterceptor returns a grpc.UnaryClientInterceptor that traces all outgoing requests from a gRPC client. The calling context should already have a *trace.Span; a child span will be created for the outgoing gRPC call. If the calling context doesn't have a span, the call will not be traced. If the client is nil, then the interceptor just passes through the request.

The functionality in gRPC that this feature relies on is currently experimental. Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Client) GRPCServerInterceptor

func (c *Client) GRPCServerInterceptor() grpc.UnaryServerInterceptor

GRPCServerInterceptor returns a grpc.UnaryServerInterceptor that enables the tracing of the incoming gRPC calls. Incoming call's context can be used to extract the span on servers that enabled this option:

span := trace.FromContext(ctx)

If the client is nil, then the interceptor just invokes the handler.

The functionality in gRPC that this feature relies on is currently experimental.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Client) HTTPHandler

func (c *Client) HTTPHandler(h http.Handler) http.Handler

HTTPHandler returns a http.Handler from the given handler that is aware of the incoming request's span. The span can be extracted from the incoming request in handler functions from incoming request's context:

span := trace.FromContext(r.Context())

The span will be auto finished by the handler.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

Example

package main

import (
	"log"
	"net/http"

	"cloud.google.com/go/trace"
)

var traceClient *trace.Client

func main() {
	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		client := http.Client{
			Transport: &trace.Transport{},
		}

		req, _ := http.NewRequest("GET", "https://metadata/users", nil)
		req = req.WithContext(r.Context())

		// The outgoing request will be traced with r's trace ID.
		if _, err := client.Do(req); err != nil {
			log.Fatal(err)
		}
	})
	http.Handle("/foo", traceClient.HTTPHandler(handler)) // traceClient is a *trace.Client
}

func (*Client) NewSpan

func (c *Client) NewSpan(name string) *Span

NewSpan returns a new trace span with the given name or nil iff the client is nil.

A new trace and span ID is generated to trace the span. Returned span need to be finished by calling Finish or FinishWait.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Client) SetSamplingPolicy

func (c *Client) SetSamplingPolicy(p SamplingPolicy)

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

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Client) SpanFromHeader

func (c *Client) SpanFromHeader(name string, header string) *Span

SpanFromHeader returns a new trace span based on a provided request header value or nil iff the client is nil.

The trace information and identifiers will be read from the header value. Otherwise, a new trace ID is made and the parent span ID is zero. For the exact format of the header value, see https://cloud.google.com/trace/docs/troubleshooting#force-trace

The name of the new span is provided as an argument.

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 header doesn't have existing tracing information, then a *Span is returned anyway, but it will not be uploaded to the server, just as when calling SpanFromRequest on an untraced request.

Most users using HTTP should use SpanFromRequest, rather than SpanFromHeader, since it provides additional functionality for HTTP requests. In particular, it will set various pieces of request information as labels on the *Span, which is not available from the header alone.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Client) SpanFromRequest

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

SpanFromRequest returns a new trace span for an HTTP request or 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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

type Decision

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

type FinishOption

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

FinishOption allows users to specify span finalizers. Deprecated: see https://cloud.google.com/trace/docs/setup/go.

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

type Parameters

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

type SamplingPolicy

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
}

SamplingPolicy provides an interface for sampling.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func NewLimitedSampler

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

type Span

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

Span contains information about one span of a trace.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func FromContext

func FromContext(ctx context.Context) *Span

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

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Span) Header

func (s *Span) Header() string

Header returns the value of the X-Cloud-Trace-Context header that should be used to propagate the span. This is the inverse of SpanFromHeader.

Most users should use NewRemoteChild unless they have specific propagation needs or want to control the naming of their span. Header() does not create a new span.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

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.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

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.

SetLabel shouldn't be called after Finish or FinishWait.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Span) TraceID

func (s *Span) TraceID() string

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

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (*Span) Traced

func (s *Span) Traced() bool

Traced reports whether the current span is sampled to be traced.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

type Transport

type Transport struct {
	// Base is the base http.RoundTripper to be used to do the actual request.
	//
	// Optional. If nil, http.DefaultTransport is used.
	Base http.RoundTripper
}

Transport is an http.RoundTripper that traces the outgoing requests.

Transport is safe for concurrent usage.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (Transport) CancelRequest

func (t Transport) CancelRequest(req *http.Request)

CancelRequest cancels an in-flight request by closing its connection.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.

func (Transport) RoundTrip

func (t Transport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip creates a trace.Span and inserts it into the outgoing request's headers. The created span can follow a parent span, if a parent is presented in the request's context.

Deprecated: see https://cloud.google.com/trace/docs/setup/go.