impl(sidekick/rust): feature flag tracing attrs (#2311)

We are introducing detailed tracing attributes to the generate Rust
code. This change makes these additional details optional until we have
stabilized the APIs.

Mainly this is to make other changes to the generator easier to grok and
apply. The observability changes look low risk but are noisy.

Author: coryan

internal/sidekick/internal/rust/annotate.go

@@ -188,20 +188,21 @@ type messageAnnotation struct {
 }
 
 type methodAnnotation struct {
-	Name                string
-	BuilderName         string
-	DocLines            []string
-	PathInfo            *api.PathInfo
-	Body                string
-	ServiceNameToPascal string
-	ServiceNameToCamel  string
-	ServiceNameToSnake  string
-	OperationInfo       *operationInfo
-	SystemParameters    []systemParameter
-	ReturnType          string
-	HasVeneer           bool
-	Attributes          []string
-	RoutingRequired     bool
+	Name                      string
+	BuilderName               string
+	DocLines                  []string
+	PathInfo                  *api.PathInfo
+	Body                      string
+	ServiceNameToPascal       string
+	ServiceNameToCamel        string
+	ServiceNameToSnake        string
+	OperationInfo             *operationInfo
+	SystemParameters          []systemParameter
+	ReturnType                string
+	HasVeneer                 bool
+	Attributes                []string
+	RoutingRequired           bool
+	DetailedTracingAttributes bool
 }
 
 type pathInfoAnnotation struct {
@@ -312,6 +313,9 @@ type pathBindingAnnotation struct {
 
 	// The variables to be substituted into the path
 	Substitutions []*bindingSubstitution
+
+	// The codec is configured to generated detailed tracing attributes.
+	DetailedTracingAttributes bool
 }
 
 // QueryParamsCanFail returns true if we serialize certain query parameters, which can fail. The code we generate
@@ -694,7 +698,7 @@ func (c *codec) annotateMessage(m *api.Message, model *api.API) {
 }
 
 func (c *codec) annotateMethod(m *api.Method) {
-	annotatePathInfo(m)
+	c.annotatePathInfo(m)
 	for _, routing := range m.Routing {
 		for _, variant := range routing.Variants {
 			routingVariantAnnotations := &routingVariantAnnotations{
@@ -712,18 +716,19 @@ func (c *codec) annotateMethod(m *api.Method) {
 	}
 	serviceName := c.ServiceName(m.Service)
 	annotation := &methodAnnotation{
-		Name:                strcase.ToSnake(m.Name),
-		BuilderName:         toPascal(m.Name),
-		Body:                bodyAccessor(m),
-		DocLines:            c.formatDocComments(m.Documentation, m.ID, m.Model.State, m.Service.Scopes()),
-		PathInfo:            m.PathInfo,
-		ServiceNameToPascal: toPascal(serviceName),
-		ServiceNameToCamel:  toCamel(serviceName),
-		ServiceNameToSnake:  toSnake(serviceName),
-		SystemParameters:    c.systemParameters,
-		ReturnType:          returnType,
-		HasVeneer:           c.hasVeneer,
-		RoutingRequired:     c.routingRequired,
+		Name:                      strcase.ToSnake(m.Name),
+		BuilderName:               toPascal(m.Name),
+		Body:                      bodyAccessor(m),
+		DocLines:                  c.formatDocComments(m.Documentation, m.ID, m.Model.State, m.Service.Scopes()),
+		PathInfo:                  m.PathInfo,
+		ServiceNameToPascal:       toPascal(serviceName),
+		ServiceNameToCamel:        toCamel(serviceName),
+		ServiceNameToSnake:        toSnake(serviceName),
+		SystemParameters:          c.systemParameters,
+		ReturnType:                returnType,
+		HasVeneer:                 c.hasVeneer,
+		RoutingRequired:           c.routingRequired,
+		DetailedTracingAttributes: c.detailedTracingAttributes,
 	}
 	if annotation.Name == "clone" {
 		// Some methods look too similar to standard Rust traits. Clippy makes
@@ -831,7 +836,7 @@ func makeBindingSubstitution(v *api.PathVariable, m *api.Method) bindingSubstitu
 	}
 }
 
-func annotatePathBinding(b *api.PathBinding, m *api.Method) *pathBindingAnnotation {
+func (c *codec) annotatePathBinding(b *api.PathBinding, m *api.Method) *pathBindingAnnotation {
 	var subs []*bindingSubstitution
 	for _, s := range b.PathTemplate.Segments {
 		if s.Variable != nil {
@@ -840,19 +845,20 @@ func annotatePathBinding(b *api.PathBinding, m *api.Method) *pathBindingAnnotati
 		}
 	}
 	return &pathBindingAnnotation{
-		PathFmt:       httpPathFmt(b.PathTemplate),
-		QueryParams:   language.QueryParams(m, b),
-		Substitutions: subs,
+		PathFmt:                   httpPathFmt(b.PathTemplate),
+		QueryParams:               language.QueryParams(m, b),
+		Substitutions:             subs,
+		DetailedTracingAttributes: c.detailedTracingAttributes,
 	}
 }
 
 // annotatePathInfo annotates the `PathInfo` and all of its `PathBinding`s.
-func annotatePathInfo(m *api.Method) {
+func (c *codec) annotatePathInfo(m *api.Method) {
 	seen := make(map[string]bool)
 	var uniqueParameters []*bindingSubstitution
 
 	for _, b := range m.PathInfo.Bindings {
-		ann := annotatePathBinding(b, m)
+		ann := c.annotatePathBinding(b, m)
 
 		// We need to keep track of unique path parameters to support
 		// implicit routing over gRPC. This is go/aip/4222.

internal/sidekick/internal/rust/codec.go

@@ -130,6 +130,12 @@ func newCodec(protobufSource bool, options map[string]string) (*codec, error) {
 				return nil, fmt.Errorf("cannot convert `per-service-features` value %q to boolean: %w", definition, err)
 			}
 			codec.perServiceFeatures = value
+		case key == "detailed-tracing-attributes":
+			value, err := strconv.ParseBool(definition)
+			if err != nil {
+				return nil, fmt.Errorf("cannot convert `detailed-tracing-attributes` value %q to boolean: %w", definition, err)
+			}
+			codec.detailedTracingAttributes = value
 		case key == "has-veneer":
 			value, err := strconv.ParseBool(definition)
 			if err != nil {
@@ -243,6 +249,12 @@ type codec struct {
 	includeGrpcOnlyMethods bool
 	// If true, the generator will produce per-client features.
 	perServiceFeatures bool
+	// If true, the generated code includes detailed tracing attributes on HTTP
+	// requests. This feature flag exists to reduce unexpected changes to the
+	// generated code until the feature is ready and well-tested.
+	// TODO(https://github.com/googleapis/google-cloud-rust/issues/3239) -
+	//   remove this flag once we switch the default.
+	detailedTracingAttributes bool
 	// If true, there is a handwritten client surface.
 	hasVeneer bool
 	// A list of types which should only be `pub(crate)`.

internal/sidekick/internal/rust/codec_test.go

@@ -183,6 +183,26 @@ func TestParseOptionsTemplateOverride(t *testing.T) {
 	checkRustPackages(t, got, want)
 }
 
+func TestParseOptionsDetailedTracingAttributes(t *testing.T) {
+	options := map[string]string{
+		"detailed-tracing-attributes": "true",
+	}
+	got, err := newCodec(false, options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !got.detailedTracingAttributes {
+		t.Errorf("expected tracing attributes to be enabled")
+	}
+
+	options = map[string]string{
+		"detailed-tracing-attributes": "--invalid--",
+	}
+	if got, err := newCodec(false, options); err == nil {
+		t.Errorf("expected an error with an invalid detailed-tracing-attributes flag, got=%v", got)
+	}
+}
+
 func TestPackageName(t *testing.T) {
 	rustPackageNameImpl(t, "test-only-overridden", map[string]string{
 		"package-name-override": "test-only-overridden",

internal/sidekick/internal/rust/templates/crate/src/transport.rs.mustache

@@ -80,7 +80,12 @@ impl super::stub::{{Codec.Name}} for {{Codec.Name}} {
             true,
         );
         {{/HasAutoPopulatedFields}}
+        {{#Codec.DetailedTracingAttributes}}
         let (builder, method, path_template) = None
+        {{/Codec.DetailedTracingAttributes}}
+        {{^Codec.DetailedTracingAttributes}}
+        let (builder, method) = None
+        {{/Codec.DetailedTracingAttributes}}
         {{#PathInfo.Bindings}}
         .or_else(|| {
             {{#Codec.HasVariablePath}}
@@ -94,7 +99,9 @@ impl super::stub::{{Codec.Name}} for {{Codec.Name}} {
             {{^Codec.HasVariablePath}}
             let path = "{{Codec.PathFmt}}".to_string();
             {{/Codec.HasVariablePath}}
+            {{#Codec.DetailedTracingAttributes}}
             let path_template = "{{Codec.PathTemplate}}";
+            {{/Codec.DetailedTracingAttributes}}
 
             let builder = self
                 .inner
@@ -113,7 +120,12 @@ impl super::stub::{{Codec.Name}} for {{Codec.Name}} {
             {{/Codec.QueryParams}}
             let builder = Ok(builder);
             {{/Codec.QueryParamsCanFail}}
+            {{#Codec.DetailedTracingAttributes}}
             Some(builder.map(|b| (b, reqwest::Method::{{Verb}}, path_template)))
+            {{/Codec.DetailedTracingAttributes}}
+            {{^Codec.DetailedTracingAttributes}}
+            Some(builder.map(|b| (b, reqwest::Method::{{Verb}})))
+            {{/Codec.DetailedTracingAttributes}}
         })
         {{/PathInfo.Bindings}}
         .ok_or_else(|| {
@@ -133,7 +145,9 @@ impl super::stub::{{Codec.Name}} for {{Codec.Name}} {
             {{/PathInfo.Bindings}}
             gax::error::Error::binding(BindingError { paths })
         })??;
+        {{#Codec.DetailedTracingAttributes}}
         let options = gax::options::internal::set_path_template(options, path_template);
+        {{/Codec.DetailedTracingAttributes}}
         let options = gax::options::internal::set_default_idempotency(
             options,
             {{! TODO(#2588) - return idempotency from the above closure }}