documentation, ci, and simplification

.github/workflows/ci.yaml

@@ -123,7 +123,7 @@ jobs:
             extratesting: go get -u github.com/labstack/echo@v3
           - go-version: 1.15.x
             dirs: v3/integrations/nrecho-v4
-            extratesting: go get -u github.com/labstack/echo/v4@main
+            extratesting: go get -u github.com/labstack/echo@master
           - go-version: 1.15.x
             dirs: v3/integrations/nrelasticsearch-v7
             extratesting: go get -u github.com/elastic/go-elasticsearch/v7@7.x

v3/go.mod

@@ -4,5 +4,6 @@ go 1.7
 
 require (
 	github.com/golang/protobuf v1.3.3
+	golang.org/x/tools v0.1.0 // indirect
 	google.golang.org/grpc v1.27.0
 )

v3/integrations/nrawssdk-v2/example/main.go

@@ -45,7 +45,7 @@ func main() {
 	}
 
 	// Instrument all new AWS clients with New Relic
-	nraws.AppendMiddlewares(&awsConfig.APIOptions, ctx, txn)
+	nraws.AppendMiddlewares(&awsConfig.APIOptions, txn)
 
 	s3Client := s3.NewFromConfig(awsConfig)
 	output, err := s3Client.ListBuckets(ctx, nil)

v3/integrations/nrawssdk-v2/go.mod

@@ -14,4 +14,5 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.6.0
 	github.com/aws/smithy-go v1.4.0
 	github.com/newrelic/go-agent/v3 v3.0.0
+	golang.org/x/tools v0.1.0 // indirect
 )

v3/integrations/nrawssdk-v2/nrawssdk.go

@@ -12,6 +12,18 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// Package nrawssdk instruments requests made by the
+// https://github.com/aws/aws-sdk-go-v2 library.
+//
+// For most operations, external segments and spans are automatically created
+// for display in the New Relic UI on the External services section. For
+// DynamoDB operations, datastore segements and spans are created and will be
+// displayed on the Databases page. All operations will also be displayed on
+// transaction traces and distributed traces.
+//
+// To use this integration, simply apply the AppendMiddlewares fuction to the apiOptions in
+// your AWS Config object before performing any AWS operations. See
+// example/main.go for a working sample.
 package nrawssdk
 
 import (
@@ -25,14 +37,15 @@ import (
 	"github.com/newrelic/go-agent/v3/newrelic"
 )
 
-type NRMiddleware struct {
-	txn            *newrelic.Transaction
-	requestContext context.Context
+type nrMiddleware struct {
+	txn *newrelic.Transaction
 }
 
 type endable interface{ End() }
 
-func (m NRMiddleware) deserializeMiddleware(stack *smithymiddle.Stack) error {
+// See https://aws.github.io/aws-sdk-go-v2/docs/middleware/ for a description of
+// AWS SDK V2 middleware.
+func (m nrMiddleware) deserializeMiddleware(stack *smithymiddle.Stack) error {
 	return stack.Deserialize.Add(smithymiddle.DeserializeMiddlewareFunc("NRDeserializeMiddleware", func(
 		ctx context.Context, in smithymiddle.DeserializeInput, next smithymiddle.DeserializeHandler) (
 		out smithymiddle.DeserializeOutput, metadata smithymiddle.Metadata, err error) {
@@ -89,10 +102,23 @@ func (m NRMiddleware) deserializeMiddleware(stack *smithymiddle.Stack) error {
 		smithymiddle.Before)
 }
 
-// AppendMiddlewares attaches New Relic middleware to the AWS Go SDK V2 for
-// instrumentation. It must be called only once per AWS configuration.
-func AppendMiddlewares(apiOptions *[]func(*smithymiddle.Stack) error, ctx context.Context, txn *newrelic.Transaction) {
-	m := NRMiddleware{txn: txn,
-		requestContext: ctx}
+// AppendMiddlewares inserts New Relic middleware in the given `apiOptions` for
+// the AWS SDK V2 for Go. It must be called only once per AWS configuration.
+//
+// Additional attributes will be added to transaction trace segments and span
+// events: aws.region, aws.requestId, and aws.operation. In addition,
+// http.statusCode will be added to span events.
+//
+// To see segments and spans for each AWS invocation, call AppendMiddlewares
+// with the AWS Config `apiOptions` and pass in your current New Relic
+// transaction. For example:
+//
+//     awsConfig, err := config.LoadDefaultConfig(ctx)
+//     if err != nil {
+//         log.Fatal(err)
+//     }
+//     nraws.AppendMiddlewares(ctx, &awsConfig.APIOptions, txn)
+func AppendMiddlewares(apiOptions *[]func(*smithymiddle.Stack) error, txn *newrelic.Transaction) {
+	m := nrMiddleware{txn: txn}
 	*apiOptions = append(*apiOptions, m.deserializeMiddleware)
 }

v3/integrations/nrawssdk-v2/nrawssdk_test.go

@@ -59,17 +59,16 @@ var fakeCreds = func() interface{} {
 	return fakeCredsWithContext{}
 }()
 
-func newConfig(instrument bool, ctx context.Context, txn *newrelic.Transaction) aws.Config {
+func newConfig(ctx context.Context, txn *newrelic.Transaction) aws.Config {
 	cfg, _ := config.LoadDefaultConfig(ctx)
 	cfg.Credentials = fakeCreds.(aws.CredentialsProvider)
 	cfg.Region = awsRegion
 	cfg.HTTPClient = &http.Client{
 		Transport: &fakeTransport{},
 	}
 
-	if instrument {
-		AppendMiddlewares(&cfg.APIOptions, ctx, txn)
-	}
+	AppendMiddlewares(&cfg.APIOptions, txn)
+
 	return cfg
 }
 
@@ -194,7 +193,7 @@ func TestInstrumentRequestExternal(t *testing.T) {
 	txn := app.StartTransaction(txnName)
 	ctx := context.TODO()
 
-	client := lambda.NewFromConfig(newConfig(true, ctx, txn))
+	client := lambda.NewFromConfig(newConfig(ctx, txn))
 
 	input := &lambda.InvokeInput{
 		ClientContext:  aws.String("MyApp"),
@@ -221,7 +220,7 @@ func TestInstrumentRequestDatastore(t *testing.T) {
 	txn := app.StartTransaction(txnName)
 	ctx := context.TODO()
 
-	client := dynamodb.NewFromConfig(newConfig(true, ctx, txn))
+	client := dynamodb.NewFromConfig(newConfig(ctx, txn))
 
 	input := &dynamodb.DescribeTableInput{
 		TableName: aws.String("thebesttable"),
@@ -264,7 +263,7 @@ func TestRetrySend(t *testing.T) {
 	txn := app.StartTransaction(txnName)
 	ctx := context.TODO()
 
-	cfg := newConfig(true, ctx, txn)
+	cfg := newConfig(ctx, txn)
 
 	cfg.HTTPClient = &http.Client{
 		Transport: &firstFailingTransport{failing: true},
@@ -360,7 +359,7 @@ func TestRequestSentTwice(t *testing.T) {
 	txn := app.StartTransaction(txnName)
 	ctx := context.TODO()
 
-	client := lambda.NewFromConfig(newConfig(true, ctx, txn))
+	client := lambda.NewFromConfig(newConfig(ctx, txn))
 
 	input := &lambda.InvokeInput{
 		ClientContext:  aws.String("MyApp"),
@@ -413,7 +412,7 @@ func TestNoRequestIDFound(t *testing.T) {
 	txn := app.StartTransaction(txnName)
 	ctx := context.TODO()
 
-	cfg := newConfig(true, ctx, txn)
+	cfg := newConfig(ctx, txn)
 	cfg.HTTPClient = &http.Client{
 		Transport: &noRequestIDTransport{},
 	}