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)	rpc.service, rpc.method
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".