Documentation
¶
Index ¶
- func DisableTracing()
- func EnableTracing()
- func GetXRayHeader(req *http.Request, headerName ...string) *header.Header
- func GetXRayHttpRequestName(req *http.Request, segNamer ...xray.SegmentNamer) string
- func Init(daemonAddr string, serviceVersion string) error
- func LogXrayAddFailure(category string, err error)
- func ResetXrayFailureCounters()
- func SetXRayServiceOff()
- func SetXRayServiceOn()
- func XRayServiceOn() bool
- func XrayFailureTotal() int64
- type XRayParentSegment
- type XSegment
- func NewSegment(serviceNameOrUrl string, parentSegment ...*XRayParentSegment) *XSegment
- func NewSegmentFromHeader(req *http.Request, traceHeaderName ...string) *XSegment
- func NewSegmentNullable(serviceNameOrUrl string, parentSegment ...*XRayParentSegment) *XSegment
- func NewSubSegmentFromContext(ctx context.Context, serviceNameOrUrl string) *XSegment
- func (x *XSegment) Capture(traceName string, executeFunc func() error, traceData ...*XTraceData) error
- func (x *XSegment) CaptureAsync(traceName string, executeFunc func() error, traceData ...*XTraceData) <-chan error
- func (x *XSegment) Close()
- func (x *XSegment) NewSubSegment(subSegmentName string) *XSegment
- func (x *XSegment) Ready() bool
- func (x *XSegment) SafeAddError(err error) error
- func (x *XSegment) SafeAddMetadata(key string, value interface{}) error
- func (x *XSegment) SetParentSegment(parentID string, traceID string)
- type XTraceData
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetXRayHeader ¶
GetXRayHeader gets header from http.request, if headerName is not specified, defaults to x-amzn-trace-id
func GetXRayHttpRequestName ¶
func GetXRayHttpRequestName(req *http.Request, segNamer ...xray.SegmentNamer) string
GetXRayHttpRequestName returns the segment name based on http request method and path, or if segmentNamer is defined, gets the name from http request host
func LogXrayAddFailure ¶ added in v1.8.3
LogXrayAddFailure records and rate-limits logging of X-Ray SafeAdd* failures. Call it any time a SafeAddMetadata or SafeAddError call returns a non-nil error. At most one log line per category per xrayLogInterval (default 1 minute) is emitted; intermediate failures are counted and reported in the next log line.
category should identify the wrapper method, e.g. "SES-SendEmail", "SNS-CreateTopic". This keeps the log output actionable — operators can grep for the category to see which wrapper is experiencing xray failures.
Design rationale: the 1,168 existing `LogXrayAddFailure("Xray", seg.SafeAdd*(...)` call sites) silently discard errors. Checking every one individually would flood logs when xray is misconfigured. This sampled approach gives visibility into systemic failures without per-call log spam.
func ResetXrayFailureCounters ¶ added in v1.8.3
func ResetXrayFailureCounters()
ResetXrayFailureCounters resets all sampled-failure state. Intended for testing only — production code should not call this.
func SetXRayServiceOff ¶
func SetXRayServiceOff()
SetXRayServiceOff turns off xray service for new objects, so that wrappers and code supporting xray will not start using xray for tracing when it is init, connect or open, existing objects are not affected by this function action
func SetXRayServiceOn ¶
func SetXRayServiceOn()
SetXRayServiceOn turns on xray service for new objects, so that wrappers and code supporting xray will start using xray for tracing, the service is set to on during its init, open, or connect etc actions, existing objects are not affected by this function action
func XRayServiceOn ¶
func XRayServiceOn() bool
XRayServiceOn returns whether xray tracing service is on or off
func XrayFailureTotal ¶ added in v1.8.3
func XrayFailureTotal() int64
XrayFailureTotal returns the process-lifetime count of SafeAdd* failures observed via LogXrayAddFailure. Useful for health-check endpoints that want to expose xray observability health as a metric without log parsing.
Types ¶
type XRayParentSegment ¶
type XSegment ¶
type XSegment struct {
Ctx context.Context
Seg *xray.Segment
// contains filtered or unexported fields
}
XSegment struct provides wrapper function for xray segment, subsegment, context, and related actions
always use NewSegment() to create XSegment object ptr
func NewSegment ¶
func NewSegment(serviceNameOrUrl string, parentSegment ...*XRayParentSegment) *XSegment
NewSegment begins a new segment for a named service or url, the context.Background() is used as the base context when creating a new segment
NOTE = ALWAYS CALL CLOSE() to End Segment After Tracing of Segment is Complete
func NewSegmentFromHeader ¶
NewSegmentFromHeader begins a new segment for a named service or url based on http request, the http.Request Context is used as the base context when creating a new segment
NOTE = ALWAYS CALL CLOSE() to End Segment After Tracing of Segment is Complete
func NewSegmentNullable ¶
func NewSegmentNullable(serviceNameOrUrl string, parentSegment ...*XRayParentSegment) *XSegment
NewSegmentNullable returns a new segment for the named service or url, if _xrayServiceOn = true, otherwise, nil is returned for *XSegment.
func NewSubSegmentFromContext ¶ added in v1.3.5
NewSubSegmentFromContext begins a new subsegment under the parent segment context, context can not be empty, and must contains parent segment info
func (*XSegment) Capture ¶
func (x *XSegment) Capture(traceName string, executeFunc func() error, traceData ...*XTraceData) error
Capture wraps xray.Capture, by beginning and closing a subsegment with traceName, and synchronously executes the provided executeFunc which contains source application's logic
traceName = descriptive name for the tracing session being tracked executeFunc = custom logic to execute within capture tracing context (context is segment context) traceData = optional additional data to add to the trace (meta, annotation, error)
func (*XSegment) CaptureAsync ¶
func (x *XSegment) CaptureAsync(traceName string, executeFunc func() error, traceData ...*XTraceData) <-chan error
CaptureAsync wraps xray.CaptureAsync, by beginning and closing a subsegment with traceName, and Asynchronously executes the provided executeFunc which contains source application's logic note = use CaptureAsync when tracing goroutine (rather than Capture) note = do not manually call Capture within goroutine to ensure segment is flushed properly
traceName = descriptive name for the tracing session being tracked executeFunc = custom logic to execute within capture tracing context (context is segment context).
WARNING: executeFunc runs in an unmanaged goroutine with no timeout. If executeFunc blocks indefinitely, the goroutine leaks and is never reclaimed. Callers MUST ensure executeFunc respects context cancellation or has its own internal timeout. Redesign with context propagation is planned for v2.0.0.
traceData = optional additional data to add to the trace (meta, annotation, error)
func (*XSegment) Close ¶
func (x *XSegment) Close()
Close will close a segment (or subsegment), always close subsegments first before closing its parent segment
func (*XSegment) NewSubSegment ¶
NewSubSegment begins a new subsegment under the parent segment context, the subSegmentName defines a descriptive name of this sub segment for tracing, subsegment.Close(nil) should be called before its parent segment Close is called
NOTE = ALWAYS CALL CLOSE() to End Segment After Tracing of Segment is Complete
func (*XSegment) SafeAddError ¶ added in v1.7.9
SafeAddError attaches an error to the underlying xray segment only when the wrapper is non-nil AND the segment is ready. It is safe to call on a nil receiver or when Seg is nil — both cases return nil without panicking. This is the production path for the common pattern `defer func() { if err != nil { seg.SafeAddError(err) } }()`.
func (*XSegment) SafeAddMetadata ¶ added in v1.7.9
SafeAddMetadata attaches metadata to the underlying xray segment only when the wrapper is non-nil AND the segment is ready (Ctx/Seg populated, not closed). It is safe to call on a nil receiver or on a wrapper whose Seg is nil — both cases return nil without panicking. This is the production path for the common pattern `defer func() { seg.SafeAddMetadata(...) }()` which must not panic when tracing is disabled or BeginSegment recovered from an internal xray panic (see NewSegment panic-recovery block).
func (*XSegment) SetParentSegment ¶
SetParentSegment sets segment's ParentID and TraceID as indicated by input parameters
type XTraceData ¶
type XTraceData struct {
Meta map[string]interface{}
Annotations map[string]interface{}
Errors map[string]error
}
XTraceData contains maps of data to add during trace activity
func (*XTraceData) AddAnnotation ¶
func (t *XTraceData) AddAnnotation(key string, data interface{})
AddAnnotation adds xray annotation to trace, each trace limits to 50 annotations, annotation = key value pair indexed for use with filter expression
func (*XTraceData) AddError ¶
func (t *XTraceData) AddError(key string, err error)
AddError adds xray error to trace, Error = client errors (4xx other than 429) Fault = server faults (5xx) Throttle = throttle errors (429 too many requests)
func (*XTraceData) AddMeta ¶
func (t *XTraceData) AddMeta(key string, data interface{})
AddMeta adds xray metadata to trace, metadata = key value pair with value of any type, including objects or lists, not indexed,
used to record data that need to be stored in the trace, but don't need to be indexed for searching
Source Files