From 430ce8adea2d0be43461e2ca783b7c17794e983f Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Thu, 30 May 2024 18:42:16 -0600 Subject: [PATCH] feat(internal/trace): deprecate OpenCensus support (#10287) * Change default for `GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING` env var flag to OpenTelemetry. * See https://togithub.com/googleapis/google-cloud-go/blob/main/debug.md\#telemetry refs: #2205 refs: #8655 --- auth/grpctransport/grpctransport.go | 2 +- auth/httptransport/httptransport.go | 2 +- debug.md | 58 ++++++++---------- internal/trace/trace.go | 92 ++++++++++++++++++----------- 4 files changed, 85 insertions(+), 69 deletions(-) diff --git a/auth/grpctransport/grpctransport.go b/auth/grpctransport/grpctransport.go index 81c956b030b7..75bda4c63897 100644 --- a/auth/grpctransport/grpctransport.go +++ b/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 diff --git a/auth/httptransport/httptransport.go b/auth/httptransport/httptransport.go index 7fea9d87e2cc..ef09c1b75238 100644 --- a/auth/httptransport/httptransport.go +++ b/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 diff --git a/debug.md b/debug.md index beec91555251..2010ed7a6f9c 100644 --- a/debug.md +++ b/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 diff --git a/internal/trace/trace.go b/internal/trace/trace.go index 97738b2cbee2..e8daf800a6a4 100644 --- a/internal/trace/trace.go +++ b/internal/trace/trace.go @@ -33,17 +33,22 @@ 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. @@ -51,47 +56,58 @@ const ( ) 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)