Skip to content

Commit

Permalink
feat(internal/trace): deprecate OpenCensus support (#10287)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@quartzmo
quartzmo authored May 31, 2024
1 parent 4832e10 commit 430ce8a
Show file tree
Hide file tree
Showing 4 changed files with 85 additions and 69 deletions.
2 changes: 1 addition & 1 deletion auth/grpctransport/grpctransport.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion auth/httptransport/httptransport.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
58 changes: 26 additions & 32 deletions debug.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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)

Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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/)
Expand Down Expand Up @@ -341,7 +337,6 @@ func main() {

```


##### Configuring context propagation

In order to pass options to OpenTelemetry trace context propagation, follow the
Expand Down Expand Up @@ -388,7 +383,6 @@ if err != nil {
defer c.Close()
```


### Metrics (experimental)

The generated clients do not create metrics. Only the following hand-written
Expand Down
92 changes: 57 additions & 35 deletions internal/trace/trace.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit 430ce8a

Please sign in to comment.