aws

README

Warning

OpenCensus and OpenTracing have merged to form OpenTelemetry, which serves as the next major version of OpenCensus and OpenTracing.

OpenTelemetry has now reached feature parity with OpenCensus, with tracing and metrics SDKs available in .NET, Golang, Java, NodeJS, and Python. All OpenCensus Github repositories, except census-instrumentation/opencensus-python, will be archived on July 31st, 2023. We encourage users to migrate to OpenTelemetry by this date.

To help you gradually migrate your instrumentation to OpenTelemetry, bridges are available in Java, Go, Python, and JS. Read the full blog post to learn more.

aws

aws package defines an exporter that publishes spans to AWS X-Ray.

Installation

go get contrib.go.opencensus.io/exporter/aws

To Do

• Publish spans in a separate goroutine
• Support propagation of http spans
• Support remote spans
• Verified works with ELB/ALB
• Report errors / exceptions
• Publish partial segments; currently only completed segments are published to aws

Documentation

Overview

Package aws provides Exporter support for AWS XRay for traces.

Index

• Constants
• func ParseTraceHeader(header string) (trace.SpanContext, bool)
• func TraceHeader(sc trace.SpanContext) string
• type Exporter
  • func NewExporter(opts ...Option) (*Exporter, error)
  • func (e *Exporter) Close() error
  • func (e *Exporter) ExportSpan(s *trace.SpanData)
  • func (e *Exporter) Flush()
• type HTTPFormat
  • func (f *HTTPFormat) SpanContextFromRequest(req *http.Request) (sc trace.SpanContext, ok bool)
  • func (f *HTTPFormat) SpanContextToRequest(sc trace.SpanContext, req *http.Request)
• type OnExport
• type Option
  • func WithAPI(api xrayiface.XRayAPI) Option
  • func WithBlacklist(blacklist []*regexp.Regexp) Option
  • func WithBufferSize(bufferSize int) Option
  • func WithInterval(interval time.Duration) Option
  • func WithOnExport(fn func(OnExport)) Option
  • func WithOrigin(origin origin) Option
  • func WithOutput(w io.Writer) Option
  • func WithRegion(region string) Option
  • func WithServiceName(name string) Option
  • func WithVersion(version string) Option

Constants

const (
	// OriginEC2 span originated from EC2
	OriginEC2 origin = "AWS::EC2::Instance"

	// OriginECS span originated from Elastic Container Service (ECS)
	OriginECS origin = "AWS::ECS::Container"

	// OriginEB span originated from Elastic Beanstalk (EB)
	OriginEB origin = "AWS::ElasticBeanstalk::Environment"
)

Functions

func ParseTraceHeader

func ParseTraceHeader(header string) (trace.SpanContext, bool)

ParseTraceHeader parses an Amazon trace header to OpenCensus span context.

func TraceHeader

func TraceHeader(sc trace.SpanContext) string

TraceHeader converts an OpenCensus span context to AWS X-Ray trace header.

Types

type Exporter

type Exporter struct {
	// contains filtered or unexported fields
}

Exporter is an implementation of trace.Exporter that uploads spans to AWS XRay

func NewExporter

func NewExporter(opts ...Option) (*Exporter, error)

NewExporter returns an implementation of trace.Exporter that uploads spans to AWS X-Ray

func (*Exporter) Close

func (e *Exporter) Close() error

Close this exporter and publish any spans that may have been buffered

func (*Exporter) ExportSpan

func (e *Exporter) ExportSpan(s *trace.SpanData)

ExportSpan exports a span to AWS X-Ray

func (*Exporter) Flush

func (e *Exporter) Flush()

type HTTPFormat

type HTTPFormat struct{}

HTTPFormat implements propagation.HTTPFormat to propagate traces in HTTP headers for for Amazon services: ELB, ALB, Lambda, etc.

func (*HTTPFormat) SpanContextFromRequest

func (f *HTTPFormat) SpanContextFromRequest(req *http.Request) (sc trace.SpanContext, ok bool)

SpanContextFromRequest extracts an AWS X-Ray Trace span context from incoming requests.

func (*HTTPFormat) SpanContextToRequest

func (f *HTTPFormat) SpanContextToRequest(sc trace.SpanContext, req *http.Request)

SpanContextToRequest modifies the given request to include a AWS X-Ray trace header.

type OnExport

type OnExport struct {
	// TraceID holds the raw aws traceID e.g. 1-581cf771-a006649127e371903a2de979
	TraceID string
}

OnExport structure passed when a root segment is published

type Option

type Option interface {
	// contains filtered or unexported methods
}

func WithAPI

func WithAPI(api xrayiface.XRayAPI) Option

WithAPI - optional manually constructed api instance

func WithBlacklist

func WithBlacklist(blacklist []*regexp.Regexp) Option

WithBlacklist filters out the spans those names match one of the given regexps.

func WithBufferSize

func WithBufferSize(bufferSize int) Option

WithBufferSize - specifies the maximum number of spans to buffer before publishing them; defaults to 100

func WithInterval

func WithInterval(interval time.Duration) Option

WithInterval - specifies longest time before buffered spans are published; defaults to 1s

func WithOnExport

func WithOnExport(fn func(OnExport)) Option

WithOnExport - function to be called when spans are published to AWS; useful if you would like the traceID used for AWS

func WithOrigin

func WithOrigin(origin origin) Option

WithOrigin - specifies the aws origin of the span; currently supported are OriginEC2, OriginECS, and OriginEB

func WithOutput

func WithOutput(w io.Writer) Option

WithOutput - optional writer for error messages

func WithRegion

func WithRegion(region string) Option

WithRegion - optional aws region to send xray messages to

func WithServiceName

func WithServiceName(name string) Option

WithServiceName - specifies the service name the exporter will report to xray

func WithVersion

func WithVersion(version string) Option

WithVersion - specifies the version of the application running