awsxrayexporter

README

AWS X-Ray Tracing Exporter for OpenTelemetry Collector

This exporter converts OpenTelemetry spans to AWS X-Ray Segment Documents and then sends them directly to X-Ray using the PutTraceSegments API.

Data Conversion

Trace IDs and Span IDs are expected to be originally generated by either AWS API Gateway or AWS ALB and propagated by them using the X-Amzn-Trace-Id HTTP header. However, other generation sources are supported by replacing Trace IDs where necessary. For consistency, you may want to consider using the X-Ray approach if generating Trace IDs within the application.

AWS X-Ray IDs are the same size as W3C Trace Context IDs but differ in that the first 32 bits of a Trace ID is the Unix epoch time when the trace was started. Since X-Ray only allows submission of Trace IDs from the past 30 days, received Trace IDs are checked. If outside the allowed range, a replacement is generated by the exporter using the current time.

The http object is populated when the component attribute value is grpc as well as http. Other synchronous call types should also result in the http object being populated.

AWS Specific Attributes

The following AWS-specific Span attributes are supported in addition to the standard names and values defined in the OpenTelemetry Semantic Conventions.

Attribute name	Notes and examples	Required?
aws.operation	The name of the API action invoked against an AWS service or resource.	No
aws.account_id	The AWS account number if accessing resource in different account.	No
aws.region	The AWS region if accessing resource in different region from app.	No
aws.request_id	AWS-generated unique identifier for the request.	No
aws.queue_url	For operations on an Amazon SQS queue, the queue's URL.	No
aws.table_name	For operations on a DynamoDB table, the name of the table.	No

Any of these values supplied are used to populate the aws object in addition to any relevant data supplied by the Span Resource object. X-Ray uses this data to generate inferred segments for the remote APIs.

Exporter Configuration

The following exporter configuration parameters are supported. They mirror and have the same affect as the comparable AWS X-Ray Daemon configuration values.

Name	Description	Default
num_workers	Maximum number of concurrent calls to AWS X-Ray to upload documents.	8
endpoint	Optionally override the default X-Ray service endpoint.
request_timeout	Number of seconds before timing out a request.	30
max_retries	Maximun number of attempts to post a batch before failing.	2
no_verify_ssl	Enable or disable TLS certificate verification.	false
proxy_address	Upload segments to AWS X-Ray through a proxy.
region	Send segments to AWS X-Ray service in a specific region.
local_mode	Local mode to skip EC2 instance metadata check.	false
resource_arn	Amazon Resource Name (ARN) of the AWS resource running the collector.
role_arn	IAM role to upload segments to a different account.

AWS Credential Configuration

This exporter follows default credential resolution for the aws-sdk-go.

Follow the guidelines for the credential configuration.

Documentation

Overview

Package awsxrayexporter implements an OpenTelemetry Collector exporter that sends trace data to AWS X-Ray in the region the collector is running in using the PutTraceSegments API.

Index

• Constants
• func GetAWSConfigSession(logger *zap.Logger, cn connAttr, cfg *Config) (*aws.Config, *session.Session, error)
• func IsTimeoutError(err error) bool
• func NewFactory() component.ExporterFactory
• func NewTraceExporter(config configmodels.Exporter, logger *zap.Logger, cn connAttr) (component.TraceExporter, error)
• func ProxyServerTransport(logger *zap.Logger, config *Config) (*http.Transport, error)
• type Config
• type Conn
• type XRay
  • func NewXRay(logger *zap.Logger, awsConfig *aws.Config, s *session.Session) XRay
• type XRayClient
  • func (c *XRayClient) PutTelemetryRecords(input *xray.PutTelemetryRecordsInput) (*xray.PutTelemetryRecordsOutput, error)
  • func (c *XRayClient) PutTraceSegments(input *xray.PutTraceSegmentsInput) (*xray.PutTraceSegmentsOutput, error)

Constants

const (
	STSEndpointPrefix         = "https://sts."
	STSEndpointSuffix         = ".amazonaws.com"
	STSAwsCnPartitionIDSuffix = ".amazonaws.com.cn" // AWS China partition.
)

AWS STS endpoint constants

Functions

func GetAWSConfigSession

func GetAWSConfigSession(logger *zap.Logger, cn connAttr, cfg *Config) (*aws.Config, *session.Session, error)

GetAWSConfigSession returns AWS config and session instances.

func IsTimeoutError

func IsTimeoutError(err error) bool

IsTimeoutError checks whether error is timeout error.

func NewFactory

func NewFactory() component.ExporterFactory

NewFactory creates a factory for AWS-Xray exporter.

func NewTraceExporter

func NewTraceExporter(config configmodels.Exporter, logger *zap.Logger, cn connAttr) (component.TraceExporter, error)

NewTraceExporter creates an component.TraceExporterOld that converts to an X-Ray PutTraceSegments request and then posts the request to the configured region's X-Ray endpoint.

func ProxyServerTransport

func ProxyServerTransport(logger *zap.Logger, config *Config) (*http.Transport, error)

ProxyServerTransport configures HTTP transport for TCP Proxy Server.

Types

type Config

type Config struct {
	configmodels.ExporterSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct.
	// Maximum number of concurrent calls to AWS X-Ray to upload documents.
	NumberOfWorkers int `mapstructure:"num_workers"`
	// X-Ray service endpoint to which the collector sends segment documents.
	Endpoint string `mapstructure:"endpoint"`
	// Number of seconds before timing out a request.
	RequestTimeoutSeconds int `mapstructure:"request_timeout_seconds"`
	// Maximum number of retries before abandoning an attempt to post data.
	MaxRetries int `mapstructure:"max_retries"`
	// Enable or disable TLS certificate verification.
	NoVerifySSL bool `mapstructure:"no_verify_ssl"`
	// Upload segments to AWS X-Ray through a proxy.
	ProxyAddress string `mapstructure:"proxy_address"`
	// Send segments to AWS X-Ray service in a specific region.
	Region string `mapstructure:"region"`
	// Local mode to skip EC2 instance metadata check.
	LocalMode bool `mapstructure:"local_mode"`
	// Amazon Resource Name (ARN) of the AWS resource running the collector.
	ResourceARN string `mapstructure:"resource_arn"`
	// IAM role to upload segments to a different account.
	RoleARN string `mapstructure:"role_arn"`
	// By default, OpenTelemetry attributes are converted to X-Ray metadata, which are not indexed.
	// Specify a list of attribute names to be converted to X-Ray annotations instead, which will be indexed.
	// See annotation vs. metadata: https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-annotations
	IndexedAttributes []string `mapstructure:"indexed_attributes"`
	// Set to true to convert all OpenTelemetry attributes to X-Ray annotation (indexed) ignoring the IndexedAttributes option.
	// Default value: false
	IndexAllAttributes bool `mapstructure:"index_all_attributes"`
}

Config defines configuration for AWS X-Ray exporter.

type Conn

type Conn struct{}

Conn implements connAttr interface.

type XRay

type XRay interface {
	PutTraceSegments(input *xray.PutTraceSegmentsInput) (*xray.PutTraceSegmentsOutput, error)
	PutTelemetryRecords(input *xray.PutTelemetryRecordsInput) (*xray.PutTelemetryRecordsOutput, error)
}

XRay defines X-Ray api call structure.

func NewXRay

func NewXRay(logger *zap.Logger, awsConfig *aws.Config, s *session.Session) XRay

NewXRay creates a new instance of the XRay client with a aws configuration and session .

type XRayClient

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

XRayClient represents X-Ray client.

func (*XRayClient) PutTelemetryRecords

func (c *XRayClient) PutTelemetryRecords(input *xray.PutTelemetryRecordsInput) (*xray.PutTelemetryRecordsOutput, error)

PutTelemetryRecords makes PutTelemetryRecords api call on X-Ray client.

func (*XRayClient) PutTraceSegments

func (c *XRayClient) PutTraceSegments(input *xray.PutTraceSegmentsInput) (*xray.PutTraceSegmentsOutput, error)

PutTraceSegments makes PutTraceSegments api call on X-Ray client.