Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 2 commits into from
May 31, 2024
+85 −69
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
81a9472
feat(internal/trace): deprecate OpenCensus support
quartzmo May 30, 2024
7875926
Merge branch 'main' into trace-otel-default
quartzmo May 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion auth/grpctransport/grpctransport.go
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading