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 ¶
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 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.
Source Files