feat(internal/trace): deprecate OpenCensus support (#10287)

* Change default for `GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING` env var flag to OpenTelemetry.
* See https://github.com/googleapis/google-cloud-go/blob/main/debug.md\#telemetry

refs: #2205
refs: #8655

Author: quartzmo

auth/grpctransport/grpctransport.go

@@ -47,7 +47,7 @@ var (
 
 // Options used to configure a [GRPCClientConnPool] from [Dial].
 type Options struct {
-	// DisableTelemetry disables default telemetry (OpenCensus). An example
+	// DisableTelemetry disables default telemetry (OpenTelemetry). An example
 	// reason to do so would be to bind custom telemetry that overrides the
 	// defaults.
 	DisableTelemetry bool

auth/httptransport/httptransport.go

@@ -33,7 +33,7 @@ type ClientCertProvider = func(*tls.CertificateRequestInfo) (*tls.Certificate, e
 
 // Options used to configure a [net/http.Client] from [NewClient].
 type Options struct {
-	// DisableTelemetry disables default telemetry (OpenCensus). An example
+	// DisableTelemetry disables default telemetry (OpenTelemetry). An example
 	// reason to do so would be to bind custom telemetry that overrides the
 	// defaults.
 	DisableTelemetry bool

debug.md

@@ -2,7 +2,7 @@
 
 **Warning: The OpenCensus project is obsolete and was archived on July 31st,
 2023.** This means that any security vulnerabilities that are found will not be
-patched. We recommend that you begin migrating to OpenCensus tracing to
+patched. We recommend that you migrate from OpenCensus tracing to
 OpenTelemetry, the successor project. See [OpenCensus](#opencensus) below for
 details.
 
@@ -181,15 +181,16 @@ func main() {
 
 **Warning: The OpenCensus project is obsolete and was archived on July 31st,
 2023.** This means that any security vulnerabilities that are found will not be
-patched. We recommend that you begin migrating to OpenCensus tracing to
-OpenTelemetry, the successor project. See [OpenCensus](#opencensus) below for
-details.
+patched. We recommend that you migrate from OpenCensus tracing to
+OpenTelemetry, the successor project. The default experimental tracing support
+for OpenCensus is now deprecated in the Google Cloud client libraries for Go.
+See [OpenCensus](#opencensus) below for details.
 
-The Google Cloud client libraries for Go still use the OpenCensus project by
-default. However, opt-in support for
-[OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) is now
-available. The transition from OpenCensus to OpenTelemetry is covered in the
-following sections.
+The Google Cloud client libraries for Go now use the
+[OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) project by
+default. Temporary opt-in support for OpenCensus is still available. The
+transition from OpenCensus to OpenTelemetry is covered in the following
+sections.
 
 ### Tracing (experimental)
 
@@ -204,17 +205,18 @@ hand-written clients are in scope for the discussion in this section:
 * [cloud.google.com/go/spanner](https://pkg.go.dev/cloud.google.com/go/spanner)
 * [cloud.google.com/go/storage](https://pkg.go.dev/cloud.google.com/go/storage)
 
-Currently, the spans created by these clients are for OpenCensus. However,
-OpenCensus users are urged to transition to OpenTelemetry as soon as possible,
-as explained in the next section. OpenTelemetry users can opt-in to experimental
-OpenTelemetry support via an environment variable, as described below.
+Currently, the spans created by these clients are for OpenTelemetry. OpenCensus
+users are urged to transition to OpenTelemetry as soon as possible, as explained
+in the next section. OpenCensus users can still opt-in to the deprecated
+OpenCensus support via an environment variable, as described below.
 
 #### OpenCensus
 
 **Warning: The OpenCensus project is obsolete and was archived on July 31st,
 2023.** This means that any security vulnerabilities that are found will not be
-patched. We recommend that you begin migrating to OpenCensus tracing to
-OpenTelemetry, the successor project.
+patched. We recommend that you migrate from OpenCensus tracing to
+OpenTelemetry, the successor project. The default experimental tracing support
+for OpenCensus is now deprecated in the Google Cloud client libraries for Go.
 
 Using the [OpenTelemetry-Go - OpenCensus Bridge](https://pkg.go.dev/go.opentelemetry.io/otel/bridge/opencensus), you can immediately begin exporting your traces with OpenTelemetry, even while
 dependencies of your application remain instrumented with OpenCensus. If you do
@@ -226,9 +228,9 @@ instrumentation are used.
 On May 29, 2024, six months after the
 [release](https://github.com/googleapis/google-cloud-go/releases/tag/v0.111.0)
 of experimental, opt-in support for OpenTelemetry tracing, the default tracing
-support in the clients above will change from OpenCensus to OpenTelemetry, and
-the experimental OpenCensus support will be marked as deprecated. To continue
-using the OpenCensus support after this change, set the environment variable
+support in the clients above was changed from OpenCensus to OpenTelemetry, and
+the experimental OpenCensus support was marked as deprecated. To continue
+using the OpenCensus support, set the environment variable
 `GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING` to the case-insensitive
 value `opencensus` before loading the client library.
 
@@ -252,6 +254,12 @@ Please refer to the following resources:
 
 #### OpenTelemetry
 
+The default experimental tracing support for OpenCensus is now deprecated in the
+Google Cloud client libraries for Go.
+
+On May 29, 2024, the default experimental tracing support in the Google Cloud
+client libraries for Go was changed from OpenCensus to OpenTelemetry.
+
 **Warning: OpenTelemetry-Go ensures
 [compatibility](https://github.com/open-telemetry/opentelemetry-go/tree/main?tab=readme-ov-file#compatibility)
 with ONLY the current supported versions of the [Go
@@ -261,18 +269,6 @@ Ensure that your Go runtime version is supported by the OpenTelemetry-Go
 [compatibility](https://github.com/open-telemetry/opentelemetry-go/tree/main?tab=readme-ov-file#compatibility)
 policy before enabling OpenTelemetry instrumentation.**
 
-To opt-in to experimental OpenTelemetry tracing currently available in the
-clients listed above, set the environment variable
-`GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING` to the case-insensitive
-value `opentelemetry` before loading the client library.
-
-```sh
-export GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING=opentelemetry
-```
-
-On May 29, 2024, the default tracing support will change from OpenCensus to
-OpenTelemetry, and this environment variable will no longer be needed.
-
 Please refer to the following resources:
 
 * [What is OpenTelemetry?](https://opentelemetry.io/docs/what-is-opentelemetry/)
@@ -341,7 +337,6 @@ func main() {
 
 ```
 
-
 ##### Configuring context propagation
 
 In order to pass options to OpenTelemetry trace context propagation, follow the
@@ -388,7 +383,6 @@ if err != nil {
 defer c.Close()
 ```
 
-
 ### Metrics (experimental)
 
 The generated clients do not create metrics. Only the following hand-written

internal/trace/trace.go

@@ -33,65 +33,81 @@ import (
 )
 
 const (
+	// Deprecated: The default experimental tracing support for OpenCensus is
+	// now deprecated in the Google Cloud client libraries for Go.
 	// TelemetryPlatformTracingOpenCensus is the value to which the environment
 	// variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING should be
 	// set to enable OpenCensus tracing.
 	TelemetryPlatformTracingOpenCensus = "opencensus"
-	// TelemetryPlatformTracingOpenCensus is the value to which the environment
+	// TelemetryPlatformTracingOpenTelemetry is the value to which the environment
 	// variable GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING should be
 	// set to enable OpenTelemetry tracing.
 	TelemetryPlatformTracingOpenTelemetry = "opentelemetry"
-	// TelemetryPlatformTracingOpenCensus is the name of the environment
-	// variable that can be set to change the default tracing from OpenCensus
-	// to OpenTelemetry.
+	// TelemetryPlatformTracingVar is the name of the environment
+	// variable that can be set to change the default tracing from OpenTelemetry
+	// to OpenCensus.
+	//
+	// The default experimental tracing support for OpenCensus is now deprecated
+	// in the Google Cloud client libraries for Go.
 	TelemetryPlatformTracingVar = "GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING"
 	// OpenTelemetryTracerName is the name given to the OpenTelemetry Tracer
 	// when it is obtained from the OpenTelemetry TracerProvider.
 	OpenTelemetryTracerName = "cloud.google.com/go"
 )
 
 var (
-	// openTelemetryTracingEnabledMu guards access to openTelemetryTracingEnabled field
-	openTelemetryTracingEnabledMu = sync.RWMutex{}
-	// openTelemetryTracingEnabled is true if the environment variable
+	// openCensusTracingEnabledMu guards access to openCensusTracingEnabled field
+	openCensusTracingEnabledMu = sync.RWMutex{}
+	// openCensusTracingEnabled is true if the environment variable
 	// GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is set to the
-	// case-insensitive value "opentelemetry".
-	openTelemetryTracingEnabled bool = strings.EqualFold(strings.TrimSpace(
-		os.Getenv(TelemetryPlatformTracingVar)), TelemetryPlatformTracingOpenTelemetry)
+	// case-insensitive value "opencensus".
+	openCensusTracingEnabled bool = strings.EqualFold(strings.TrimSpace(
+		os.Getenv(TelemetryPlatformTracingVar)), TelemetryPlatformTracingOpenCensus)
 )
 
-// SetOpenTelemetryTracingEnabledField programmatically sets the value provided by GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING for the purpose of unit testing.
-// Do not invoke it directly. Intended for use only in unit tests. Restore original value after each test.
+// SetOpenTelemetryTracingEnabledField programmatically sets the value provided
+// by GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING for the purpose of
+// unit testing. Do not invoke it directly. Intended for use only in unit tests.
+// Restore original value after each test.
+//
+// The default experimental tracing support for OpenCensus is now deprecated in
+// the Google Cloud client libraries for Go.
 func SetOpenTelemetryTracingEnabledField(enabled bool) {
-	openTelemetryTracingEnabledMu.Lock()
-	defer openTelemetryTracingEnabledMu.Unlock()
-	openTelemetryTracingEnabled = enabled
+	openCensusTracingEnabledMu.Lock()
+	defer openCensusTracingEnabledMu.Unlock()
+	openCensusTracingEnabled = !enabled
 }
 
+// Deprecated: The default experimental tracing support for OpenCensus is now
+// deprecated in the Google Cloud client libraries for Go.
+//
 // IsOpenCensusTracingEnabled returns true if the environment variable
-// GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is NOT set to the
-// case-insensitive value "opentelemetry".
+// GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is set to the
+// case-insensitive value "opencensus".
 func IsOpenCensusTracingEnabled() bool {
-	return !IsOpenTelemetryTracingEnabled()
+	openCensusTracingEnabledMu.RLock()
+	defer openCensusTracingEnabledMu.RUnlock()
+	return openCensusTracingEnabled
 }
 
 // IsOpenTelemetryTracingEnabled returns true if the environment variable
-// GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is set to the
-// case-insensitive value "opentelemetry".
+// GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is NOT set to the
+// case-insensitive value "opencensus".
 func IsOpenTelemetryTracingEnabled() bool {
-	openTelemetryTracingEnabledMu.RLock()
-	defer openTelemetryTracingEnabledMu.RUnlock()
-	return openTelemetryTracingEnabled
+	return !IsOpenCensusTracingEnabled()
 }
 
 // StartSpan adds a span to the trace with the given name. If IsOpenCensusTracingEnabled
 // returns true, the span will be an OpenCensus span. If IsOpenTelemetryTracingEnabled
 // returns true, the span will be an OpenTelemetry span. Set the environment variable
 // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING to the case-insensitive
-// value "opentelemetry" before loading the package to use OpenTelemetry tracing.
-// The default will remain OpenCensus until May 29, 2024, at which time the default will
-// switch to "opentelemetry" and explicitly setting the environment variable to
-// "opencensus" will be required to continue using OpenCensus tracing.
+// value "opencensus" before loading the package to use OpenCensus tracing.
+// The default was OpenCensus until May 29, 2024, at which time the default was
+// changed to "opencensus". Explicitly setting the environment variable to
+// "opencensus" is required to continue using OpenCensus tracing.
+//
+// The default experimental tracing support for OpenCensus is now deprecated in
+// the Google Cloud client libraries for Go.
 func StartSpan(ctx context.Context, name string) context.Context {
 	if IsOpenTelemetryTracingEnabled() {
 		ctx, _ = otel.GetTracerProvider().Tracer(OpenTelemetryTracerName).Start(ctx, name)
@@ -105,10 +121,13 @@ func StartSpan(ctx context.Context, name string) context.Context {
 // returns true, the span will be an OpenCensus span. If IsOpenTelemetryTracingEnabled
 // returns true, the span will be an OpenTelemetry span. Set the environment variable
 // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING to the case-insensitive
-// value "opentelemetry" before loading the package to use OpenTelemetry tracing.
-// The default will remain OpenCensus until May 29, 2024, at which time the default will
-// switch to "opentelemetry" and explicitly setting the environment variable to
-// "opencensus" will be required to continue using OpenCensus tracing.
+// value "opencensus" before loading the package to use OpenCensus tracing.
+// The default was OpenCensus until May 29, 2024, at which time the default was
+// changed to "opencensus". Explicitly setting the environment variable to
+// "opencensus" is required to continue using OpenCensus tracing.
+//
+// The default experimental tracing support for OpenCensus is now deprecated in
+// the Google Cloud client libraries for Go.
 func EndSpan(ctx context.Context, err error) {
 	if IsOpenTelemetryTracingEnabled() {
 		span := ottrace.SpanFromContext(ctx)
@@ -191,10 +210,13 @@ func httpStatusCodeToOCCode(httpStatusCode int) int32 {
 // OpenCensus span. If IsOpenTelemetryTracingEnabled returns true, the expected
 // span must be an OpenTelemetry span. Set the environment variable
 // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING to the case-insensitive
-// value "opentelemetry" before loading the package to use OpenTelemetry tracing.
-// The default will remain OpenCensus until May 29, 2024, at which time the default will
-// switch to "opentelemetry" and explicitly setting the environment variable to
-// "opencensus" will be required to continue using OpenCensus tracing.
+// value "opencensus" before loading the package to use OpenCensus tracing.
+// The default was OpenCensus until May 29, 2024, at which time the default was
+// changed to "opencensus". Explicitly setting the environment variable to
+// "opencensus" is required to continue using OpenCensus tracing.
+//
+// The default experimental tracing support for OpenCensus is now deprecated in
+// the Google Cloud client libraries for Go.
 func TracePrintf(ctx context.Context, attrMap map[string]interface{}, format string, args ...interface{}) {
 	if IsOpenTelemetryTracingEnabled() {
 		attrs := otAttrs(attrMap)