AWS SDK for Go v2 now supports traces and metrics

[lucix-aws]

As of the 2024-09-20 release, the AWS SDK for Go v2 is now instrument to record both trace spans and client-side metrics.

Background

Service clients now have two additional configuration options:

• tracing.TracerProvider - entry point into creating tracers and client traces
• metrics.MeterProvider - entry point into creating meters and instruments

While heavily inspired by the OpenTelemetry (OTEL) specifications for tracing and metrics, the APIs for these new configs are defined independently in smithy-go. This allows us to retain control over the APIs and component boundaries therein.

By default, clients default to no-op implementations for both tracing and metrics. In order to provide an out-of-the-box solution for connecting a concrete implementation, we have released adapters for the OTEL tracing and metrics SDKs in standalone, independently consumable go modules:

• https://pkg.go.dev/github.com/aws/smithy-go/tracing/smithyoteltracing allows you to adapt a concrete OTEL trace.TracerProvider to be used with a service client's TracerProvider.
• https://pkg.go.dev/github.com/aws/smithy-go/metrics/smithyotelmetrics allows you to adapt a concrete OTEL metric.MeterProvider to be used with a service client's metrics.MeterProvider.

Tracing

Quickstart guide

The new Adapt() API in smithyoteltracing is used to connect a concrete OTEL SDK TracerProvider to SDK client config:

import (
	"github.com/aws/aws-sdk-go-v2/service/s3"
	"github.com/aws/smithy-go/tracing/smithyoteltracing"
	"go.opentelemetry.io/otel/trace"
)

var provider trace.TracerProvider // OTEL tracer provider which you have configured
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
	o.TracerProvider = smithyoteltracing.Adapt(provider)
})

SDK operations have been instrumented with a span hierarchy that roughly breaks down the high-level components of the operation lifecycle (e.g. request serialization, signing, retry loop).

Metrics

The new Adapt() API in smithyotelmetrics is used to connect a concrete OTEL SDK MeterProvider to SDK client config:

Quickstart guide

import (
	"github.com/aws/aws-sdk-go-v2/service/s3"
	"github.com/aws/smithy-go/metrics/smithyotelmetrics"
	"go.opentelemetry.io/otel/metric"
)

var provider metric.TracerProvider // OTEL meter provider which you have configured
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
	o.MeterProvider = smithyotelmetrics.Adapt(provider)
})

Supported metrics

In this initial release, SDK clients collect the following metrics:

Metric Name	Unit	Type	Description	Attributes (Dimensions)
client.call.duration	s	Histogram	Overall call duration (including retries and time to send or receive request and response body)	rpc.service, rpc.method
client.call.attempts	{attempt}	MonotonicCounter	The number of attempts for an individual operation	rpc.service, rpc.method
client.call.errors	{error}	MonotonicCounter	The number of errors for an operation	rpc.service, rpc.method, exception.type
client.call.attempt	duration	s	Histogram	The time it takes to connect to the service, send the request, and get back HTTP status code and headers (including time queued waiting to be sent)
client.call.resolve_endpoint_duration	s	Histogram	The time it takes to resolve an endpoint (endpoint resolver, not DNS) for the request	rpc.service, rpc.method
client.call.deserialization duration	s	Histogram	The time it takes to deserialize a message body	rpc.service, rpc.method
client.call.auth.signing duration	s	Histogram	The time it takes to sign a request	rpc.service, rpc.method, auth.scheme_id
client.call.auth.resolve_identity_duration	s	Histogram	The time taken to acquire an identity (AWS credentials, bearer token, etc) from an Identity Provider	rpc.service, rpc.method, auth.scheme_id

We plan to add HTTP client metrics in a future release. This is tracked in #2809.

Feedback

We'd like to hear from you about your experience with tracing and metrics in this SDK. If you have any feedback or suggestions, or would like to report a bug, please don't hesitate to file an issue in this repository.

[gerardvt]

Excellent writeup, very helpful.
Thank you.
Minor spelling @"concrete implementatiojn".