feat(storage): add grpc metrics experimental options

storage/experimental/experimental.go

@@ -0,0 +1,40 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// All options in this package are experimental.
+
+package experimental
+
+import (
+	"time"
+
+	"cloud.google.com/go/storage/internal"
+	"go.opentelemetry.io/otel/sdk/metric"
+	"google.golang.org/api/option"
+)
+
+// WithMetricInterval how often to emit metrics when using NewPeriodicReader
+// https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#NewPeriodicReader
+// https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#WithInterval
+func WithMetricInterval(metricInterval time.Duration) option.ClientOption {
+	return internal.WithMetricInterval.(func(time.Duration) option.ClientOption)(metricInterval)
+}
+
+// WithMetricExporter provide alternate client-side meterProvider
+// to emit metrics through.
+// Must implement interface metric.Exporter:
+// https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#Exporter
+func WithMetricExporter(ex *metric.Exporter) option.ClientOption {
+	return internal.WithMetricInterval.(func(*metric.Exporter) option.ClientOption)(ex)
+}

storage/grpc_client.go

@@ -129,7 +129,7 @@ func newGRPCStorageClient(ctx context.Context, opts ...storageOption) (storageCl
 
 	if !config.disableClientMetrics {
 		// Do not fail client creation if enabling metrics fails.
-		if metricsContext, err := enableClientMetrics(ctx, s); err == nil {
+		if metricsContext, err := enableClientMetrics(ctx, s, config); err == nil {
 			s.metricsContext = metricsContext
 			s.clientOption = append(s.clientOption, metricsContext.clientOpts...)
 		} else {

storage/grpc_metrics.go

@@ -134,8 +134,6 @@ func newPreparedResource(ctx context.Context, project string, resourceOptions []
 }
 
 type metricsContext struct {
-	// project used by exporter
-	project string
 	// client options passed to gRPC channels
 	clientOpts []option.ClientOption
 	// instance of metric reader used by gRPC client-side metrics
@@ -154,29 +152,36 @@ func createHistogramView(name string, boundaries []float64) metric.View {
 	})
 }
 
-func newGRPCMetricContext(ctx context.Context, project string) (*metricsContext, error) {
-	preparedResource, err := newPreparedResource(ctx, project, []resource.Option{resource.WithDetectors(gcp.NewDetector())})
-	if err != nil {
-		return nil, err
-	}
-	// Implementation requires a project, if one is not determined possibly user
-	// credentials. Then we will fail stating gRPC Metrics require a project-id.
-	if project == "" && preparedResource.projectToUse != "" {
-		return nil, fmt.Errorf("google cloud project is required to start client-side metrics")
-	}
-	// If projectTouse isn't the same as project provided to Storage client, then
-	// emit a log stating which project is being used to emit metrics to.
-	if project != preparedResource.projectToUse {
-		log.Printf("The Project ID configured for metrics is %s, but the Project ID of the storage client is %s. Make sure that the service account in use has the required metric writing role (roles/monitoring.metricWriter) in the project projectIdToUse or metrics will not be written.", preparedResource.projectToUse, project)
-	}
-	meOpts := []mexporter.Option{
-		mexporter.WithProjectID(preparedResource.projectToUse),
-		mexporter.WithMetricDescriptorTypeFormatter(metricFormatter),
-		mexporter.WithCreateServiceTimeSeries(),
-		mexporter.WithMonitoredResourceDescription(monitoredResourceName, []string{"project_id", "location", "cloud_platform", "host_id", "instance_id", "api"})}
-	exporter, err := mexporter.New(meOpts...)
-	if err != nil {
-		return nil, err
+func newGRPCMetricContext(ctx context.Context, project string, config storageConfig) (*metricsContext, error) {
+	var exporter metric.Exporter
+	meterOpts := []metric.Option{}
+	if config.metricExporter != nil {
+		exporter = *config.metricExporter
+	} else {
+		preparedResource, err := newPreparedResource(ctx, project, []resource.Option{resource.WithDetectors(gcp.NewDetector())})
+		if err != nil {
+			return nil, err
+		}
+		meterOpts = append(meterOpts, metric.WithResource(preparedResource.resource))
+		// Implementation requires a project, if one is not determined possibly user
+		// credentials. Then we will fail stating gRPC Metrics require a project-id.
+		if project == "" && preparedResource.projectToUse == "" {
+			return nil, fmt.Errorf("google cloud project is required to start client-side metrics")
+		}
+		// If projectTouse isn't the same as project provided to Storage client, then
+		// emit a log stating which project is being used to emit metrics to.
+		if project != preparedResource.projectToUse {
+			log.Printf("The Project ID configured for metrics is %s, but the Project ID of the storage client is %s. Make sure that the service account in use has the required metric writing role (roles/monitoring.metricWriter) in the project projectIdToUse or metrics will not be written.", preparedResource.projectToUse, project)
+		}
+		meOpts := []mexporter.Option{
+			mexporter.WithProjectID(preparedResource.projectToUse),
+			mexporter.WithMetricDescriptorTypeFormatter(metricFormatter),
+			mexporter.WithCreateServiceTimeSeries(),
+			mexporter.WithMonitoredResourceDescription(monitoredResourceName, []string{"project_id", "location", "cloud_platform", "host_id", "instance_id", "api"})}
+		exporter, err = mexporter.New(meOpts...)
+		if err != nil {
+			return nil, err
+		}
 	}
 	// Metric views update histogram boundaries to be relevant to GCS
 	// otherwise default OTel histogram boundaries are used.
@@ -185,11 +190,13 @@ func newGRPCMetricContext(ctx context.Context, project string) (*metricsContext,
 		createHistogramView("grpc.client.attempt.rcvd_total_compressed_message_size", sizeHistogramBoundaries()),
 		createHistogramView("grpc.client.attempt.sent_total_compressed_message_size", sizeHistogramBoundaries()),
 	}
-	provider := metric.NewMeterProvider(
-		metric.WithReader(metric.NewPeriodicReader(&exporterLogSuppressor{exporter: exporter}, metric.WithInterval(time.Minute))),
-		metric.WithResource(preparedResource.resource),
-		metric.WithView(metricViews...),
-	)
+	interval := time.Minute
+	if config.metricInterval > time.Minute {
+		interval = config.metricInterval
+	}
+	meterOpts = append(meterOpts, metric.WithReader(metric.NewPeriodicReader(&exporterLogSuppressor{exporter: exporter}, metric.WithInterval(interval))),
+		metric.WithView(metricViews...))
+	provider := metric.NewMeterProvider(meterOpts...)
 	mo := opentelemetry.MetricsOptions{
 		MeterProvider: provider,
 		Metrics: opentelemetry.DefaultMetrics().Add(
@@ -209,22 +216,21 @@ func newGRPCMetricContext(ctx context.Context, project string) (*metricsContext,
 		option.WithGRPCDialOption(grpc.WithDefaultCallOptions(grpc.StaticMethodCallOption{})),
 	}
 	context := &metricsContext{
-		project:    preparedResource.projectToUse,
 		clientOpts: opts,
 		provider:   provider,
 		close:      createShutdown(ctx, provider),
 	}
 	return context, nil
 }
 
-func enableClientMetrics(ctx context.Context, s *settings) (*metricsContext, error) {
+func enableClientMetrics(ctx context.Context, s *settings, config storageConfig) (*metricsContext, error) {
 	var project string
 	c, err := transport.Creds(ctx, s.clientOption...)
 	if err == nil {
 		project = c.ProjectID
 	}
 	// Enable client-side metrics for gRPC
-	metricsContext, err := newGRPCMetricContext(ctx, project)
+	metricsContext, err := newGRPCMetricContext(ctx, project, config)
 	if err != nil {
 		return nil, fmt.Errorf("gRPC Metrics: %w", err)
 	}

storage/internal/experimental.go

@@ -0,0 +1,30 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// All options in this package are experimental.
+
+package internal
+
+var (
+	// WithMetricInterval how often to emit metrics when using NewPeriodicReader
+	// https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#NewPeriodicReader
+	// https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#WithInterval
+	WithMetricInterval any
+
+	// WithMetricExporter provide alternate client-side meterProvider
+	// to emit metrics through.
+	// Must implement interface metric.Exporter:
+	// https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#Exporter
+	WithMetricExporter any
+)

storage/option.go

@@ -15,16 +15,28 @@
 package storage
 
 import (
+	"time"
+
+	storageinternal "cloud.google.com/go/storage/internal"
+	"go.opentelemetry.io/otel/sdk/metric"
 	"google.golang.org/api/option"
 	"google.golang.org/api/option/internaloption"
 )
 
+func init() {
+	// initialize experimental options
+	storageinternal.WithMetricInterval = withMetricInterval
+	storageinternal.WithMetricExporter = withMetricExporter
+}
+
 // storageConfig contains the Storage client option configuration that can be
 // set through storageClientOptions.
 type storageConfig struct {
 	useJSONforReads      bool
 	readAPIWasSet        bool
 	disableClientMetrics bool
+	metricExporter       *metric.Exporter
+	metricInterval       time.Duration
 }
 
 // newStorageConfig generates a new storageConfig with all the given
@@ -108,3 +120,31 @@ func WithDisabledClientMetrics() option.ClientOption {
 func (w *withDisabledClientMetrics) ApplyStorageOpt(c *storageConfig) {
 	c.disableClientMetrics = w.disabledClientMetrics
 }
+
+type withMeterOptions struct {
+	internaloption.EmbeddableAdapter
+	// set sampling interval
+	interval time.Duration
+}
+
+func withMetricInterval(interval time.Duration) option.ClientOption {
+	return &withMeterOptions{interval: interval}
+}
+
+func (w *withMeterOptions) ApplyStorageOpt(c *storageConfig) {
+	c.metricInterval = w.interval
+}
+
+type withMetricExporterConfig struct {
+	internaloption.EmbeddableAdapter
+	// exporter override
+	metricExporter *metric.Exporter
+}
+
+func withMetricExporter(ex *metric.Exporter) option.ClientOption {
+	return &withMetricExporterConfig{metricExporter: ex}
+}
+
+func (w *withMetricExporterConfig) ApplyStorageOpt(c *storageConfig) {
+	c.metricExporter = w.metricExporter
+}

storage/option_test.go

@@ -16,6 +16,7 @@ package storage
 
 import (
 	"testing"
+	"time"
 
 	"github.com/google/go-cmp/cmp"
 	"google.golang.org/api/option"
@@ -81,6 +82,17 @@ func TestApplyStorageOpt(t *testing.T) {
 				disableClientMetrics: true,
 			},
 		},
+		{
+			desc: "change metrics interval",
+			opts: []option.ClientOption{withMetricInterval(time.Minute * 5)},
+			want: storageConfig{
+				useJSONforReads:      false,
+				readAPIWasSet:        false,
+				disableClientMetrics: true,
+				metricInterval:       time.Minute * 5,
+				metricExporter:       nil,
+			},
+		},
 	} {
 		t.Run(test.desc, func(t *testing.T) {
 			var got storageConfig