Add AWS X-Ray Exporter

exporter/awsxrayexporter/Makefile

@@ -0,0 +1 @@
+include ../../Makefile.Common

exporter/awsxrayexporter/README.md

@@ -0,0 +1,63 @@
+# AWS X-Ray Tracing Exporter for OpenTelemetry Collector
+
+This exporter converts OpenTelemetry spans to 
+[AWS X-Ray Segment Documents](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html)
+and then sends them directly to X-Ray using the 
+[PutTraceSegements](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) 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 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      |
+| `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](https://docs.aws.amazon.com/sdk-for-go/api/index.html).
+
+Follow the [guidelines](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) for the 
+credential configuration.

exporter/awsxrayexporter/awsxray.go

@@ -0,0 +1,77 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package awsxrayexporter
+
+import (
+	"context"
+
+	"github.com/aws/aws-sdk-go/service/xray"
+	"github.com/open-telemetry/opentelemetry-collector/config/configmodels"
+	"github.com/open-telemetry/opentelemetry-collector/consumer/consumerdata"
+	"github.com/open-telemetry/opentelemetry-collector/exporter"
+	"github.com/open-telemetry/opentelemetry-collector/exporter/exporterhelper"
+	"go.uber.org/zap"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awsxrayexporter/translator"
+)
+
+// NewTraceExporter creates an exporter.TraceExporter that just drops the
+// received data and logs debugging messages.
+func NewTraceExporter(config configmodels.Exporter, logger *zap.Logger, cn connAttr) (exporter.TraceExporter, error) {
+	typeLog := zap.String("type", config.Type())
+	nameLog := zap.String("name", config.Name())
+	awsConfig, session, err := GetAWSConfigSession(logger, cn, config.(*Config))
+	if err != nil {
+		return nil, err
+	}
+	xrayClient := NewXRay(logger, awsConfig, session)
+	return exporterhelper.NewTraceExporter(
+		config,
+		func(ctx context.Context, td consumerdata.TraceData) (int, error) {
+			logger.Debug("TraceExporter", typeLog, nameLog, zap.Int("#spans", len(td.Spans)))
+			droppedSpans, input := assembleRequest(td, logger)
+			logger.Debug("request: " + input.String())
+			output, err := xrayClient.PutTraceSegments(input)
+			logger.Debug("response: " + output.String())
+			if output != nil && output.UnprocessedTraceSegments != nil {
+				droppedSpans += len(output.UnprocessedTraceSegments)
+			}
+			return droppedSpans, err
+		},
+		exporterhelper.WithTracing(true),
+		exporterhelper.WithMetrics(false),
+		exporterhelper.WithShutdown(logger.Sync),
+	)
+}
+
+func assembleRequest(td consumerdata.TraceData, logger *zap.Logger) (int, *xray.PutTraceSegmentsInput) {
+	documents := make([]*string, len(td.Spans))
+	droppedSpans := int(0)
+	for i, span := range td.Spans {
+		if span == nil || span.Name == nil {
+			droppedSpans++
+			continue
+		}
+		spanName := span.Name.Value
+		jsonStr, err := translator.MakeSegmentDocumentString(spanName, span)
+		if err != nil {
+			droppedSpans++
+			logger.Warn("Unable to convert span", zap.Error(err))
+		}
+		logger.Debug(jsonStr)
+		documents[i] = &jsonStr
+	}
+	return droppedSpans, &xray.PutTraceSegmentsInput{TraceSegmentDocuments: documents}
+}

exporter/awsxrayexporter/awsxray_test.go

@@ -0,0 +1,195 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package awsxrayexporter
+
+import (
+	"context"
+	"fmt"
+	"reflect"
+	"testing"
+	"time"
+
+	resourcepb "github.com/census-instrumentation/opencensus-proto/gen-go/resource/v1"
+	tracepb "github.com/census-instrumentation/opencensus-proto/gen-go/trace/v1"
+	"github.com/golang/protobuf/ptypes/timestamp"
+	"github.com/golang/protobuf/ptypes/wrappers"
+	"github.com/open-telemetry/opentelemetry-collector/consumer/consumerdata"
+	"github.com/open-telemetry/opentelemetry-collector/exporter"
+	"github.com/stretchr/testify/assert"
+	"go.uber.org/zap"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awsxrayexporter/translator"
+)
+
+func TestTraceExport(t *testing.T) {
+	traceExporter := initializeTraceExporter()
+	ctx := context.Background()
+	td := constructSpanData()
+	err := traceExporter.ConsumeTraceData(ctx, td)
+	assert.Nil(t, err)
+}
+
+func initializeTraceExporter() exporter.TraceExporter {
+	logger := zap.NewNop()
+	factory := Factory{}
+	config := factory.CreateDefaultConfig()
+	config.(*Config).Region = "us-east-1"
+	config.(*Config).LocalMode = true
+	mconn := new(mockConn)
+	mconn.sn, _ = getDefaultSession(logger)
+	traceExporter, err := NewTraceExporter(config, logger, mconn)
+	if err != nil {
+		panic(err)
+	}
+	return traceExporter
+}
+
+func constructSpanData() consumerdata.TraceData {
+	resource := constructResource()
+	spans := make([]*tracepb.Span, 2)
+	spans[0] = constructHTTPClientSpan()
+	spans[0].Resource = resource
+	spans[1] = constructHTTPServerSpan()
+	spans[1].Resource = resource
+	return consumerdata.TraceData{
+		Node:         nil,
+		Resource:     resource,
+		Spans:        spans,
+		SourceFormat: "oc",
+	}
+}
+
+func constructResource() *resourcepb.Resource {
+	labels := make(map[string]string)
+	labels[translator.ServiceNameAttribute] = "signup_aggregator"
+	labels[translator.ServiceVersionAttribute] = "1.1.12"
+	labels[translator.ContainerNameAttribute] = "signup_aggregator"
+	labels[translator.ContainerImageAttribute] = "otel/signupaggregator"
+	labels[translator.ContainerTagAttribute] = "v1"
+	labels[translator.CloudProviderAttribute] = "aws"
+	labels[translator.CloudAccountAttribute] = "999999998"
+	labels[translator.CloudRegionAttribute] = "us-west-2"
+	labels[translator.CloudZoneAttribute] = "us-west-1b"
+	return &resourcepb.Resource{
+		Type:   "container",
+		Labels: labels,
+	}
+}
+
+func constructHTTPClientSpan() *tracepb.Span {
+	attributes := make(map[string]interface{})
+	attributes[translator.ComponentAttribute] = translator.HTTPComponentType
+	attributes[translator.MethodAttribute] = "GET"
+	attributes[translator.URLAttribute] = "https://api.example.com/users/junit"
+	attributes[translator.StatusCodeAttribute] = 200
+	endTime := time.Now().Round(time.Second)
+	startTime := endTime.Add(-90 * time.Second)
+	spanAttributes := constructSpanAttributes(attributes)
+
+	return &tracepb.Span{
+		TraceId:      translator.NewTraceID(),
+		SpanId:       translator.NewSegmentID(),
+		ParentSpanId: translator.NewSegmentID(),
+		Name:         &tracepb.TruncatableString{Value: "/users/junit"},
+		Kind:         tracepb.Span_CLIENT,
+		StartTime:    convertTimeToTimestamp(startTime),
+		EndTime:      convertTimeToTimestamp(endTime),
+		Status: &tracepb.Status{
+			Code:    0,
+			Message: "OK",
+		},
+		SameProcessAsParentSpan: &wrappers.BoolValue{Value: false},
+		Tracestate: &tracepb.Span_Tracestate{
+			Entries: []*tracepb.Span_Tracestate_Entry{
+				{Key: "foo", Value: "bar"},
+				{Key: "a", Value: "b"},
+			},
+		},
+		Attributes: &tracepb.Span_Attributes{
+			AttributeMap: spanAttributes,
+		},
+	}
+}
+
+func constructHTTPServerSpan() *tracepb.Span {
+	attributes := make(map[string]interface{})
+	attributes[translator.ComponentAttribute] = translator.HTTPComponentType
+	attributes[translator.MethodAttribute] = "GET"
+	attributes[translator.URLAttribute] = "https://api.example.com/users/junit"
+	attributes[translator.UserAgentAttribute] = "PostmanRuntime/7.16.3"
+	attributes[translator.ClientIPAttribute] = "192.168.15.32"
+	attributes[translator.StatusCodeAttribute] = 200
+	endTime := time.Now().Round(time.Second)
+	startTime := endTime.Add(-90 * time.Second)
+	spanAttributes := constructSpanAttributes(attributes)
+
+	return &tracepb.Span{
+		TraceId:      translator.NewTraceID(),
+		SpanId:       translator.NewSegmentID(),
+		ParentSpanId: translator.NewSegmentID(),
+		Name:         &tracepb.TruncatableString{Value: "/users/junit"},
+		Kind:         tracepb.Span_SERVER,
+		StartTime:    convertTimeToTimestamp(startTime),
+		EndTime:      convertTimeToTimestamp(endTime),
+		Status: &tracepb.Status{
+			Code:    0,
+			Message: "OK",
+		},
+		SameProcessAsParentSpan: &wrappers.BoolValue{Value: false},
+		Tracestate: &tracepb.Span_Tracestate{
+			Entries: []*tracepb.Span_Tracestate_Entry{
+				{Key: "foo", Value: "bar"},
+				{Key: "a", Value: "b"},
+			},
+		},
+		Attributes: &tracepb.Span_Attributes{
+			AttributeMap: spanAttributes,
+		},
+	}
+}
+
+func convertTimeToTimestamp(t time.Time) *timestamp.Timestamp {
+	if t.IsZero() {
+		return nil
+	}
+	nanoTime := t.UnixNano()
+	return &timestamp.Timestamp{
+		Seconds: nanoTime / 1e9,
+		Nanos:   int32(nanoTime % 1e9),
+	}
+}
+
+func constructSpanAttributes(attributes map[string]interface{}) map[string]*tracepb.AttributeValue {
+	attrs := make(map[string]*tracepb.AttributeValue)
+	for key, value := range attributes {
+		valType := reflect.TypeOf(value)
+		var attrVal tracepb.AttributeValue
+		if valType.Kind() == reflect.Int {
+			attrVal = tracepb.AttributeValue{Value: &tracepb.AttributeValue_IntValue{
+				IntValue: int64(value.(int)),
+			}}
+		} else if valType.Kind() == reflect.Int64 {
+			attrVal = tracepb.AttributeValue{Value: &tracepb.AttributeValue_IntValue{
+				IntValue: value.(int64),
+			}}
+		} else {
+			attrVal = tracepb.AttributeValue{Value: &tracepb.AttributeValue_StringValue{
+				StringValue: &tracepb.TruncatableString{Value: fmt.Sprintf("%v", value)},
+			}}
+		}
+		attrs[key] = &attrVal
+	}
+	return attrs
+}

exporter/awsxrayexporter/config.go

@@ -0,0 +1,42 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package awsxrayexporter
+
+import "github.com/open-telemetry/opentelemetry-collector/config/configmodels"
+
+// Config defines configuration for AWS X-Ray exporter.
+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.
+	Concurrency 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"`
+}