feat(internal/trace): export internal/trace package constants and vars (

#9242)

* Export constants and vars for use by handwritten clients
* Update docs for transition date to OpenTelemetry tracing default.

internal/trace/trace.go

@@ -32,16 +32,33 @@ import (
 )
 
 const (
-	telemetryPlatformTracingOpenCensus    = "opencensus"
-	telemetryPlatformTracingOpenTelemetry = "opentelemetry"
-	telemetryPlatformTracingVar           = "GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING"
+	// 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
+	// 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 = "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 (
-	// TODO(chrisdsmith): Should the name of the OpenTelemetry tracer be public and mutable?
-	openTelemetryTracerName     string = "cloud.google.com/go"
-	openTelemetryTracingEnabled bool   = strings.EqualFold(strings.TrimSpace(
-		os.Getenv(telemetryPlatformTracingVar)), telemetryPlatformTracingOpenTelemetry)
+	// OpenTelemetryTracingEnabled is true if the environment variable
+	// GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is set to the
+	// case-insensitive value "opentelemetry".
+	//
+	// Do not access directly. Use instead IsOpenTelemetryTracingEnabled or
+	// IsOpenCensusTracingEnabled. Intended for use only in unit tests. Restore
+	// original value after each test.
+	OpenTelemetryTracingEnabled bool = strings.EqualFold(strings.TrimSpace(
+		os.Getenv(TelemetryPlatformTracingVar)), TelemetryPlatformTracingOpenTelemetry)
 )
 
 // IsOpenCensusTracingEnabled returns true if the environment variable
@@ -55,20 +72,20 @@ func IsOpenCensusTracingEnabled() bool {
 // GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING is set to the
 // case-insensitive value "opentelemetry".
 func IsOpenTelemetryTracingEnabled() bool {
-	return openTelemetryTracingEnabled
+	return OpenTelemetryTracingEnabled
 }
 
 // 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 [TBD], at which time the default will
+// 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.
 func StartSpan(ctx context.Context, name string) context.Context {
 	if IsOpenTelemetryTracingEnabled() {
-		ctx, _ = otel.GetTracerProvider().Tracer(openTelemetryTracerName).Start(ctx, name)
+		ctx, _ = otel.GetTracerProvider().Tracer(OpenTelemetryTracerName).Start(ctx, name)
 	} else {
 		ctx, _ = trace.StartSpan(ctx, name)
 	}
@@ -80,7 +97,7 @@ func StartSpan(ctx context.Context, name string) context.Context {
 // 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 [TBD], at which time the default will
+// 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.
 func EndSpan(ctx context.Context, err error) {
@@ -166,7 +183,7 @@ func httpStatusCodeToOCCode(httpStatusCode int) int32 {
 // 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 [TBD], at which time the default will
+// 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.
 func TracePrintf(ctx context.Context, attrMap map[string]interface{}, format string, args ...interface{}) {

internal/trace/trace_test.go

@@ -41,11 +41,11 @@ var (
 )
 
 func TestStartSpan_OpenCensus(t *testing.T) {
-	old := openTelemetryTracingEnabled
-	openTelemetryTracingEnabled = false
+	old := OpenTelemetryTracingEnabled
+	OpenTelemetryTracingEnabled = false
 	te := testutil.NewTestExporter()
 	t.Cleanup(func() {
-		openTelemetryTracingEnabled = old
+		OpenTelemetryTracingEnabled = old
 		te.Unregister()
 	})
 
@@ -95,12 +95,12 @@ func TestStartSpan_OpenCensus(t *testing.T) {
 }
 
 func TestStartSpan_OpenTelemetry(t *testing.T) {
-	old := openTelemetryTracingEnabled
-	openTelemetryTracingEnabled = true
+	old := OpenTelemetryTracingEnabled
+	OpenTelemetryTracingEnabled = true
 	ctx := context.Background()
 	te := testutil.NewOpenTelemetryTestExporter()
 	t.Cleanup(func() {
-		openTelemetryTracingEnabled = old
+		OpenTelemetryTracingEnabled = old
 		te.Unregister(ctx)
 	})