goa: github.com/raphael/goa/http/middleware/xray Index | Files

package xray

import "github.com/raphael/goa/http/middleware/xray"

Package xray contains middleware that creates AWS X-Ray segments from the HTTP requests and responses and send the segments to an AWS X-ray daemon.

The server 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. It stores the request segment in the context. User code can further configure the segment for example to set a service version or record an error.

The client middleware wraps the client Doer and works by extracing the segment from the request context. It creates a new sub-segment and updates the request context with the latest segment before making the request.

Index

Package Files

doc.go middleware.go segment.go wrap_doer.go wrap_transport.go

func New Uses

func New(service, daemon string) (func(http.Handler) http.Handler, 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. 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:

if s := ctx.Value(SegKey); s != nil {
  segment := s.(*xray.Segment)
}
sub := segment.NewSubsegment("external-service")
defer sub.Close()
err := client.MakeRequest()
if err != nil {
    sub.Error = xray.Wrap(err)
}
return

An X-Ray trace is limited to 500 KB of segment data (JSON) being submitted for it. See: https://aws.amazon.com/xray/pricing/

Traces running for multiple minutes may encounter additional dynamic limits, resulting in the trace being limited to less than 500 KB. The workaround is to send less data -- fewer segments, subsegments, annotations, or metadata. And perhaps split up a single large trace into several different traces.

Here are some observations of the relationship between trace duration and the number of bytes that could be sent successfully:

- 49 seconds: 543 KB
- 2.4 minutes: 51 KB
- 6.8 minutes: 14 KB
- 1.4 hours:   14 KB

Besides those varying size limitations, a trace may be open for up to 7 days.

func WrapDoer Uses

func WrapDoer(doer goahttp.Doer) goahttp.Doer

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

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 HTTPSegment Uses

type HTTPSegment struct {
    *xray.Segment
    http.ResponseWriter
}

HTTPSegment represents an AWS X-Ray segment document for HTTP services. It wraps the AWS X-Ray segment with the http response writer.

func (*HTTPSegment) Hijack Uses

func (s *HTTPSegment) Hijack() (net.Conn, *bufio.ReadWriter, error)

Hijack supports the http.Hijacker interface.

func (*HTTPSegment) RecordRequest Uses

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

RecordRequest traces a request.

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

func (*HTTPSegment) RecordResponse Uses

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

RecordResponse traces a response.

It sets Throttle, Fault, Error and HTTP.Response

func (*HTTPSegment) Write Uses

func (s *HTTPSegment) Write(p []byte) (int, error)

Write records the HTTP response content length and error (if any) and calls the corresponding ResponseWriter method.

func (*HTTPSegment) WriteHeader Uses

func (s *HTTPSegment) WriteHeader(code int)

WriteHeader records the HTTP response code and calls the corresponding ResponseWriter method.

Package xray imports 10 packages (graph). Updated 2019-07-21. Refresh now. Tools for package owners.