xray

package
v2.2.5+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2020 License: MIT Imports: 10 Imported by: 4

Documentation

Overview

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func New

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

func WrapDoer(doer goahttp.Doer) goahttp.Doer

WrapDoer wraps a goa HTTP 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),
}

Types

type HTTPSegment

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

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

Hijack supports the http.Hijacker interface.

func (*HTTPSegment) RecordRequest

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

RecordRequest traces a request.

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

func (*HTTPSegment) RecordResponse

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

RecordResponse traces a response.

It sets Throttle, Fault, Error and HTTP.Response

func (*HTTPSegment) Write

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

func (s *HTTPSegment) WriteHeader(code int)

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL