examples/opentelemetry: demonstrate enabling experimental metrics (#8388)

examples/features/opentelemetry/README.md

@@ -2,6 +2,8 @@
 
 This example shows how to configure OpenTelemetry on a client and server, and
 shows what type of telemetry data it can produce for certain RPCs.
+This example shows how to enable experimental gRPC metrics, which are disabled
+by default and must be explicitly configured on the client and/or server.
 
 ## Try it
 

examples/features/opentelemetry/client/main.go

@@ -63,8 +63,18 @@ func main() {
 	// Configure W3C Trace Context Propagator for traces
 	textMapPropagator := otelpropagation.TraceContext{}
 	do := opentelemetry.DialOption(opentelemetry.Options{
-		MetricsOptions: opentelemetry.MetricsOptions{MeterProvider: meterProvider},
-		TraceOptions:   oteltracing.TraceOptions{TracerProvider: traceProvider, TextMapPropagator: textMapPropagator},
+		MetricsOptions: opentelemetry.MetricsOptions{
+			MeterProvider: meterProvider,
+			// These are example experimental gRPC metrics, which are disabled
+			// by default and must be explicitly enabled. For the full,
+			// up-to-date list of metrics, see:
+			// https://grpc.io/docs/guides/opentelemetry-metrics/#instruments
+			Metrics: opentelemetry.DefaultMetrics().Add(
+				"grpc.client.attempt.started",
+				"grpc.client.attempt.duration",
+			),
+		},
+		TraceOptions: oteltracing.TraceOptions{TracerProvider: traceProvider, TextMapPropagator: textMapPropagator},
 	})
 
 	go http.ListenAndServe(*prometheusEndpoint, promhttp.Handler())

examples/features/opentelemetry/server/main.go

@@ -71,8 +71,18 @@ func main() {
 	// Configure W3C Trace Context Propagator for traces
 	textMapPropagator := otelpropagation.TraceContext{}
 	so := opentelemetry.ServerOption(opentelemetry.Options{
-		MetricsOptions: opentelemetry.MetricsOptions{MeterProvider: meterProvider},
-		TraceOptions:   oteltracing.TraceOptions{TracerProvider: traceProvider, TextMapPropagator: textMapPropagator}})
+		MetricsOptions: opentelemetry.MetricsOptions{
+			MeterProvider: meterProvider,
+			// These are example experimental gRPC metrics, which are disabled
+			// by default and must be explicitly enabled. For the full,
+			// up-to-date list of metrics, see:
+			// https://grpc.io/docs/guides/opentelemetry-metrics/#instruments
+			Metrics: opentelemetry.DefaultMetrics().Add(
+				"grpc.server.call.started",
+				"grpc.server.call.duration",
+			),
+		},
+		TraceOptions: oteltracing.TraceOptions{TracerProvider: traceProvider, TextMapPropagator: textMapPropagator}})
 
 	go http.ListenAndServe(*prometheusEndpoint, promhttp.Handler())
 

stats/opentelemetry/example_test.go

@@ -25,7 +25,7 @@ import (
 	"go.opentelemetry.io/otel/sdk/metric"
 )
 
-func Example_dialOption() {
+func ExampleDialOption_basic() {
 	// This is setting default bounds for a view. Setting these bounds through
 	// meter provider from SDK is recommended, as API calls in this module
 	// provide default bounds, but these calls are not guaranteed to be stable
@@ -64,7 +64,7 @@ func Example_dialOption() {
 	defer cc.Close()
 }
 
-func Example_serverOption() {
+func ExampleServerOption_methodFilter() {
 	reader := metric.NewManualReader()
 	provider := metric.NewMeterProvider(metric.WithReader(reader))
 	opts := opentelemetry.Options{
@@ -128,3 +128,24 @@ func ExampleMetrics_enableSome() {
 	}
 	defer cc.Close()
 }
+
+func ExampleOptions_addExperimentalMetrics() {
+	opts := opentelemetry.Options{
+		MetricsOptions: opentelemetry.MetricsOptions{
+			// These are example experimental gRPC metrics, which are disabled
+			// by default and must be explicitly enabled. For the full,
+			// up-to-date list of metrics, see:
+			// https://grpc.io/docs/guides/opentelemetry-metrics/#instruments
+			Metrics: opentelemetry.DefaultMetrics().Add(
+				"grpc.client.attempt.started",
+				"grpc.client.attempt.duration",
+			),
+		},
+	}
+	do := opentelemetry.DialOption(opts)
+	cc, err := grpc.NewClient("<target string>", do, grpc.WithTransportCredentials(insecure.NewCredentials()))
+	if err != nil {
+		// Handle error.
+	}
+	defer cc.Close()
+}