Smithy Go

To set up the Smithy Go code generators, ensure you have the correct versions of Java and Go installed, and use the provided Gradle wrapper to avoid version conflicts.

Prerequisites:

• Java 17: Required. Note that Java 14 is incompatible with Gradle 5.x. On macOS, if you have multiple versions, set your JAVA_HOME using: export JAVA_HOME=$(/usr/libexec/java_home -v 17).
• Go 1.17: Required.
• Gradle: Do not use brew install gradle as it installs Gradle 6.x, which is incompatible. Instead, use the ./gradlew script provided in the repository to automatically install the correct version.

Setup Steps (from the smithy-go/codegen directory):

1. Install Java 17 and Go 1.17.
2. Run ./gradlew test to execute basic tests.
3. To run codegen-specific tests, navigate to the test directory and use the relative path to the gradle wrapper: cd smithy-go-codegen-test; ../gradlew build.

# Set JAVA_HOME on macOS if needed
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

# Run basic tests
./gradlew test

# Run codegen tests
cd smithy-go-codegen-test
../gradlew build

Smithy uses a decoupled serialization pattern. Instead of encoding directly to a byte slice (like json.Marshaler), types implement the Serializable interface, which accepts a ShapeSerializer. This allows the same data structure to be serialized into different formats (e.g., JSON, XML, or HTTP headers) depending on the implementation of the serializer provided.

Typically, a code-generated Serialize method will call WriteStruct, then call a helper method to serialize individual members, and finally call CloseStruct.

// Example of how a generated type implements Serializable
func (v *PutItemInput) Serialize(s smithy.ShapeSerializer) {
	s.WriteStruct(schemas.PutItemInput)
	v.SerializeMembers(s)
	s.CloseStruct()
}

func (v *PutItemInput) SerializeMembers(s smithy.ShapeSerializer) {
	if v.TableName != nil {
		s.WriteString(schemas.PutItemInput_TableName, *v.TableName)
	}
	if v.Item != nil {
		serializeAttributeMap(s, schemas.PutItemInput_Item, v.Item)
	}
}

When using Smithy tracing APIs, you can set key-value pairs in a smithy.Properties container. These pairs are automatically propagated to the underlying OTEL SDK.

Supported Types

The adapter natively supports the following attribute types (and their slice variants):

• bool
• int
• int64
• float64
• string

Key and Value Stringification

If a key is a string and the value is one of the supported types above, it is passed directly. For other types, the adapter follows these rules:

1. If the value implements the String() method, that value is used.
2. Otherwise, the adapter uses the Go-string representation via fmt.Sprintf("%#v", ...).

Example of key stringification behavior:

type key struct{}
func (k key) String() string { return "app.key" }

type key2 struct{}
// (No String() method)

// Inside a tracing context:
o.Properties.Set("app.version", "bar") // Result: ("app.version", "bar")
o.Properties.Set(key{}, "baz")         // Result: ("app.key", "baz")
o.Properties.Set(key2{}, "qux")        // Result: ("main.key2{}", "qux")

The smithyoteltracing package provides an adapter that allows you to use a standard OpenTelemetry (OTEL) Go SDK TracerProvider with Smithy-based clients (such as the AWS SDK for Go v2).

To use it, call smithyoteltracing.Adapt(provider) and assign the result to the TracerProvider field in your client's options configuration.

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

func main() {
	exporter, err := stdouttrace.New()
	if err != nil {
		panic(err)
	}

	cfg, err := config.LoadDefaultConfig(context.Background())
	if err != nil {
		panic(err)
	}

	// Create a standard OTEL TracerProvider
	provider := trace.NewTracerProvider(trace.WithBatcher(exporter))

	// Wrap the provider using Adapt() and pass it to the client options
	svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
		o.TracerProvider = smithyoteltracing.Adapt(provider)
	})
	// ...
}

The smithyotelmetrics package provides an adapter to bridge the OpenTelemetry (OTEL) Go SDK with Smithy-based clients. To use it, call Adapt and pass in a concrete OTEL SDK MeterProvider. The resulting object can be assigned to the MeterProvider field in a Smithy client's options (e.g., in an AWS SDK for Go v2 service client).

import (
	"context"
	"time"

	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/service/s3"
	"github.com/aws/smithy-go/metrics/smithyotelmetrics"
	"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
	"go.opentelemetry.io/otel/sdk/metric"
)

func main() {
	ctx := context.Background()
	cfg, err := config.LoadDefaultConfig(ctx)
	if err != nil {
		panic(err)
	}

	// 1. Setup an OTEL exporter (e.g., OTLP via HTTP)
	exporter, err := otlpmetrichttp.New(ctx, otlpmetrichttp.WithEndpointURL("http://localhost:4318"))
	if err != nil {
		panic(err)
	}

	// 2. Create an OTEL MeterProvider with a periodic reader
	reader := metric.NewPeriodicReader(exporter, metric.WithInterval(time.Second))
	provider := metric.NewMeterProvider(metric.WithReader(reader))

	// 3. Use smithyotelmetrics.Adapt to wrap the provider for the Smithy client
	svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
		o.MeterProvider = smithyotelmetrics.Adapt(provider)
	})
	
	_ = svc
}