Documentation
¶
Overview ¶
Package xray contains unary and streaming server and client interceptors that create AWS X-Ray segments from the gRPC requests and responses and send the segments to an AWS X-ray daemon.
The server interceptor works by extracting the tracing information setup by the tracing server middleware. The tracing server middleware must be chained before adding this middleware. It creates a new segment and stores the segment in the RPC's context. User code can further configure the segment for example to set a service version or record an error.
The client interceptor works by extracing the segment from the RPC's context and creates a new sub-segment. It updates the RPC context with the latest trace information.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewStreamServer ¶
func NewStreamServer(service, daemon string) (grpc.StreamServerInterceptor, error)
NewStreamServer is similar to NewUnaryServer except it is used for streaming endpoints.
func NewUnaryServer ¶
func NewUnaryServer(service, daemon string) (grpc.UnaryServerInterceptor, error)
NewUnaryServer returns a server middleware that sends AWS X-Ray segments to the daemon running at the given address. 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. It extracts the trace information from the incoming unary request metadata using the tracing middleware package. The tracing middleware must be mounted on the service.
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.
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 StreamClient ¶
func StreamClient(host string) grpc.StreamClientInterceptor
StreamClient is the streaming endpoint middleware equivalent for UnaryClient.
func UnaryClient ¶
func UnaryClient(host string) grpc.UnaryClientInterceptor
UnaryClient middleware creates XRay subsegments if a segment is found in the context and stores the subsegment to the context. It also sets the trace information in the context which is used by the tracing middleware. This middleware must be mounted before the tracing middleware.
Types ¶
type GRPCSegment ¶
GRPCSegment represents an AWS X-Ray segment document for gRPC services.
func (*GRPCSegment) RecordError ¶
func (s *GRPCSegment) RecordError(err error)
RecordError sets Throttle, Fault, Error, and HTTP.Response.
func (*GRPCSegment) RecordRequest ¶
RecordRequest traces a request.
It sets Http.Request & Namespace (ex: "remote")
func (*GRPCSegment) RecordResponse ¶
func (s *GRPCSegment) RecordResponse(resp any)
RecordResponse traces a response.
Source Files