github.com/goadesign/goa/middleware/xray

xray

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

Overview

Index

Package files

middleware.go net_conn_testing.go segment.go test_expectations.go transport.go wrap_doer.go

func New

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

func NewID() string

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

func NewTraceID

func NewTraceID() string

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

func WithSegment

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

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

func WrapDoer

func WrapDoer(wrapped client.Doer) client.Doer

WrapDoer wraps a goa client Doer, and creates xray subsegments for traced requests.

func WrapTransport

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

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 Exception

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

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

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

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

Response describes a HTTP response.

type Segment

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

func ContextSegment(ctx context.Context) *Segment

ContextSegment extracts the segment set in the context with WithSegment.

func NewSegment

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

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

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

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

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

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

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

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

func (s *Segment) Close()

Close closes the segment by setting its EndTime.

func (*Segment) NewSubsegment

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

NewSubsegment creates a subsegment of s.

func (*Segment) RecordContextResponse

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

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

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

RecordRequest traces a request.

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

func (*Segment) RecordResponse

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

RecordResponse traces a response.

It sets Throttle, Fault, Error and HTTP.Response

type StackEntry

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.

type TestClientExpectation

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

TestClientExpectation is a generic mock.

func NewTestClientExpectation

func NewTestClientExpectation() *TestClientExpectation

NewTestClientExpectation creates a new *TestClientExpectation

func (*TestClientExpectation) Expect

func (c *TestClientExpectation) Expect(fn string, e interface{})

Expect records the request handler in the list of expected request calls.

func (*TestClientExpectation) ExpectNTimes

func (c *TestClientExpectation) ExpectNTimes(n int, fn string, e interface{})

ExpectNTimes records the request handler n times in the list of expected request calls.

func (*TestClientExpectation) Expectation

func (c *TestClientExpectation) Expectation(fn string) interface{}

Expectation removes the expectation for the function with the given name from the expected calls if there is one and returns it. If there is no (more) expectations for the function, it prints a warning to stderr and returns nil.

func (*TestClientExpectation) MetExpectations

func (c *TestClientExpectation) MetExpectations() error

MetExpectations returns nil if there no expectation left to be called and if there is no call that was made that did not match an expectation. It returns an error describing what is left to be called or what was called with no expectation otherwise.

type TestNetConn

type TestNetConn struct {
    *TestClientExpectation
}

TestNetConn is a mock net.Conn

func NewTestNetConn

func NewTestNetConn() *TestNetConn

NewTestNetConn creates a mock net.Conn which uses expectations set by the tests to implement the behavior.

func (*TestNetConn) Close

func (c *TestNetConn) Close() error

Close runs any preset expectation.

func (*TestNetConn) LocalAddr

func (c *TestNetConn) LocalAddr() net.Addr

LocalAddr runs any preset expectation.

func (*TestNetConn) Read

func (c *TestNetConn) Read(b []byte) (n int, err error)

Read runs any preset expectation.

func (*TestNetConn) RemoteAddr

func (c *TestNetConn) RemoteAddr() net.Addr

RemoteAddr runs any preset expectation.

func (*TestNetConn) SetDeadline

func (c *TestNetConn) SetDeadline(t time.Time) error

SetDeadline runs any preset expectation.

func (*TestNetConn) SetReadDeadline

func (c *TestNetConn) SetReadDeadline(t time.Time) error

SetReadDeadline runs any preset expectation.

func (*TestNetConn) SetWriteDeadline

func (c *TestNetConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline runs any preset expectation.

func (*TestNetConn) Write

func (c *TestNetConn) Write(b []byte) (n int, err error)

Write runs any preset expectation.

Generated by godoc2md