goa: github.com/goadesign/goa/middleware/xray Index | Files

package xray

import "github.com/goadesign/goa/middleware/xray"

Index

Package Files

client.go middleware.go segment.go transport.go

func New Uses

func New(service, daemon string) (goa.Middleware, error)

New returns a middleware that sends AWS X-Ray segments to the daemon running at the given address.

service is the name of the service reported to X-Ray. daemon is the hostname (including port) of the X-Ray daemon collecting the segments.

The middleware works by extracting the trace information from the context using the tracing middleware package. The tracing middleware must be mounted first on the service.

The middleware stores the request segment in the context. Use ContextSegment to retrieve it. User code can further configure the segment for example to set a service version or record an error.

User code may create child segments using the Segment NewSubsegment method for tracing requests to external services. Such segments should be closed via the Close method once the request completes. The middleware takes care of closing the top level segment. Typical usage:

segment := xray.ContextSegment(ctx)
sub := segment.NewSubsegment("external-service")
defer sub.Close()
err := client.MakeRequest()
if err != nil {
    sub.Error = xray.Wrap(err)
}
return

func NewID Uses

func NewID() string

NewID is a span ID creation algorithm which produces values that are compatible with AWS X-Ray.

func NewTraceID Uses

func NewTraceID() string

NewTraceID is a trace ID creation algorithm which produces values that are compatible with AWS X-Ray.

func WithSegment Uses

func WithSegment(ctx context.Context, s *Segment) context.Context

WithSegment creates a context containing the given segment. Use ContextSegment to retrieve it.

func WrapTransport Uses

func WrapTransport(rt http.RoundTripper) http.RoundTripper

WrapTransport wraps a http RoundTripper with a RoundTripper which creates subsegments of the segment in each request's context. The subsegments created this way have their namespace set to "remote". The request's ctx must be set and contain the current request segment as set by the xray middleware.

Example of how to wrap http.Client's transport:

httpClient := &http.Client{
  Transport: WrapTransport(http.DefaultTransport),
}

type Cause Uses

type Cause struct {
    // ID to segment where error originated, exclusive with other
    // fields.
    ID  string `json:"id,omitempty"`
    // WorkingDirectory when error occurred. Exclusive with ID.
    WorkingDirectory string `json:"working_directory,omitempty"`
    // Exceptions contains the details on the error(s) that occurred
    // when the request as processing.
    Exceptions []*Exception `json:"exceptions,omitempty"`
}

Cause list errors that happens during the request.

type Doer Uses

type Doer interface {
    Do(*http.Request) (*http.Response, error)
}

Doer is the http Client interface.

func WrapClient Uses

func WrapClient(ctx context.Context, c *http.Client) Doer

WrapClient wraps a http client and creates subsegments of the segment in the context for each request it makes. The subsegments created this way have their namespace set to "remote".

ctx must contain the current request segment as set by the xray middleware or the client passed as argument is returned.

type Exception Uses

type Exception struct {
    // Message contains the error message.
    Message string `json:"message"`
    // Stack is the error stack trace as initialized via the
    // github.com/pkg/errors package.
    Stack []*StackEntry `json:"stack"`
}

Exception describes an error.

type HTTP Uses

type HTTP struct {
    // Request contains the data reported about the incoming request.
    Request *Request `json:"request,omitempty"`
    // Response contains the data reported about the HTTP response.
    Response *Response `json:"response,omitempty"`
}

HTTP describes a HTTP request.

type Request Uses

type Request struct {
    Method        string `json:"method,omitempty"`
    URL           string `json:"url,omitempty"`
    UserAgent     string `json:"user_agent,omitempty"`
    ClientIP      string `json:"client_ip,omitempty"`
    ContentLength int64  `json:"content_length"`
}

Request describes a HTTP request.

type Response Uses

type Response struct {
    Status        int   `json:"status"`
    ContentLength int64 `json:"content_length"`
}

Response describes a HTTP response.

type Segment Uses

type Segment struct {
    // Mutex used to synchronize access to segment.
    *sync.Mutex
    // Name is the name of the service reported to X-Ray.
    Name string `json:"name"`
    // Namespace identifies the source that created the segment.
    Namespace string `json:"namespace"`
    // Type is either the empty string or "subsegment".
    Type string `json:"type,omitempty"`
    // ID is a unique ID for the segment.
    ID  string `json:"id"`
    // TraceID is the ID of the root trace.
    TraceID string `json:"trace_id,omitempty"`
    // ParentID is the ID of the parent segment when it is from a
    // remote service. It is only initialized for the root segment.
    ParentID string `json:"parent_id,omitempty"`
    // StartTime is the segment start time.
    StartTime float64 `json:"start_time,omitempty"`
    // EndTime is the segment end time.
    EndTime float64 `json:"end_time,omitempty"`
    // InProgress is true if the segment hasn't completed yet.
    InProgress bool `json:"in_progress"`
    // HTTP contains the HTTP request and response information and is
    // only initialized for the root segment.
    HTTP *HTTP `json:"http,omitempty"`
    // Cause contains information about an error that occurred while
    // processing the request.
    Cause *Cause `json:"cause,omitempty"`
    // Error is true when a request causes an internal error. It is
    // automatically set by Close when the response status code is
    // 500 or more.
    Error bool `json:"error"`
    // Fault is true when a request results in an error that is due
    // to the user. Typically it should be set when the response
    // status code is between 400 and 500 (but not 429).
    Fault bool `json:"fault"`
    // Throttle is true when a request is throttled. It is set to
    // true when the segment closes and the response status code is
    // 429. Client code may set it to true manually as well.
    Throttle bool `json:"throttle"`
    // Annotations contains the segment annotations.
    Annotations map[string]interface{} `json:"annotations,omitempty"`
    // Metadata contains the segment metadata.
    Metadata map[string]map[string]interface{} `json:"metadata,omitempty"`
    // Subsegments contains all the subsegments.
    Subsegments []*Segment `json:"subsegments,omitempty"`
    // Parent is the subsegment parent, it's nil for the root
    // segment.
    Parent *Segment `json:"-"`
    // contains filtered or unexported fields
}

Segment represents a AWS X-Ray segment document.

func ContextSegment Uses

func ContextSegment(ctx context.Context) *Segment

ContextSegment extracts the segment set in the context with WithSegment.

func NewSegment Uses

func NewSegment(name, traceID, spanID string, conn net.Conn) *Segment

NewSegment creates a new segment that gets written to the given connection on close.

func (*Segment) AddAnnotation Uses

func (s *Segment) AddAnnotation(key string, value string)

AddAnnotation adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddBoolAnnotation Uses

func (s *Segment) AddBoolAnnotation(key string, value bool)

AddBoolAnnotation adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddBoolMetadata Uses

func (s *Segment) AddBoolMetadata(key string, value bool)

AddBoolMetadata adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddInt64Annotation Uses

func (s *Segment) AddInt64Annotation(key string, value int64)

AddInt64Annotation adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddInt64Metadata Uses

func (s *Segment) AddInt64Metadata(key string, value int64)

AddInt64Metadata adds a key-value pair that can be queried by AWS X-Ray.

func (*Segment) AddMetadata Uses

func (s *Segment) AddMetadata(key string, value string)

AddMetadata adds a key-value pair to the metadata.default attribute. Metadata is not queryable, but is recorded.

func (*Segment) Capture Uses

func (s *Segment) Capture(name string, fn func())

Capture creates a subsegment to record the execution of the given function. Usage:

s := xray.ContextSegment(ctx)
s.Capture("slow-func", func() {
    // ... some long executing code
})

func (*Segment) Close Uses

func (s *Segment) Close()

Close closes the segment by setting its EndTime.

func (*Segment) NewSubsegment Uses

func (s *Segment) NewSubsegment(name string) *Segment

NewSubsegment creates a subsegment of s.

func (*Segment) RecordContextResponse Uses

func (s *Segment) RecordContextResponse(ctx context.Context)

RecordContextResponse traces a context response if present in the context

It sets Throttle, Fault, Error and HTTP.Response

func (*Segment) RecordError Uses

func (s *Segment) RecordError(e error)

RecordError traces an error. The client may also want to initialize the fault field of s.

The trace contains a stack trace and a cause for the error if the argument was created using one of the New, Errorf, Wrap or Wrapf functions of the github.com/pkg/errors package. Otherwise the Stack and Cause fields are empty.

func (*Segment) RecordRequest Uses

func (s *Segment) RecordRequest(req *http.Request, namespace string)

RecordRequest traces a request.

It sets Http.Request & Namespace (ex: "remote")

func (*Segment) RecordResponse Uses

func (s *Segment) RecordResponse(resp *http.Response)

RecordResponse traces a response.

It sets Throttle, Fault, Error and HTTP.Response

type StackEntry Uses

type StackEntry struct {
    // Path to code file
    Path string `json:"path"`
    // Line number
    Line int `json:"line"`
    // Label is the line label if any
    Label string `json:"label,omitempty"`
}

StackEntry represents an entry in a error stacktrace.

Package xray imports 14 packages (graph). Updated 2017-05-28. Refresh now. Tools for package owners.