Add options to opencensus bridge, and install tracer instead of retur…

…ning

CHANGELOG.md

@@ -16,6 +16,11 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Add the "Roll the dice" getting started application example in `go.opentelemetry.io/otel/example/dice`. (#4539)
 - The `WithWriter` and `WithPrettyPrint` options to `go.opentelemetry.io/otel/exporters/stdout/stdoutmetric` to set a custom `io.Writer`, and allow displaying the output in human-readable JSON (#4507).
+- Add `go.opentelemetry.io/otel/bridge/opencensus.InstallTraceBridge`, which installs the OpenCensus trace bridge, and replaces `opencensus.NewTracer`. (#4567)
+
+### Deprecated
+
+- Deprecate `go.opentelemetry.io/otel/bridge/opencensus.NewTracer` in favor of `opencensus.InstallTraceBridge`. (#4567)
 
 ## [1.19.0-rc.1/0.42.0-rc.1] 2023-09-14
 

bridge/opencensus/README.md

@@ -66,8 +66,7 @@ import (
 	"go.opentelemetry.io/otel"
 )
 
-tracer := otel.GetTracerProvider().Tracer("bridge")
-octrace.DefaultTracer = opencensus.NewTracer(tracer)
+opencensus.InstallTraceBridge()
 ```
 
 Be sure to set the `Tracer` name to your instrumentation package name instead of `"bridge"`.

bridge/opencensus/bridge.go

@@ -26,10 +26,21 @@ import (
 // NewTracer returns an implementation of the OpenCensus Tracer interface which
 // uses OpenTelemetry APIs.  Using this implementation of Tracer "upgrades"
 // libraries that use OpenCensus to OpenTelemetry to facilitate a migration.
+//
+// Deprecated: Use InstallTraceBridge instead.
 func NewTracer(tracer trace.Tracer) octrace.Tracer {
 	return internal.NewTracer(tracer)
 }
 
+// InstallTraceBridge installs the OpenCensus trace bridge, which overwrites
+// the global OpenCensus tracer implementation. Once the bridge is installed,
+// spans recorded using OpenCensus are redirected to the OpenTelemetry SDK.
+func InstallTraceBridge(opts ...TraceOption) {
+	cfg := newTraceConfig(opts)
+	tracer := cfg.tp.Tracer(scopeName)
+	octrace.DefaultTracer = internal.NewTracer(tracer)
+}
+
 // OTelSpanContextToOC converts from an OpenTelemetry SpanContext to an
 // OpenCensus SpanContext, and handles any incompatibilities with the global
 // error handler.

bridge/opencensus/config.go

@@ -0,0 +1,65 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package opencensus // import "go.opentelemetry.io/otel/bridge/opencensus"
+
+import (
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/trace"
+)
+
+const scopeName = "go.opentelemetry.io/otel/bridge/opencensus"
+
+// newTraceConfig returns a config configured with options.
+func newTraceConfig(options []TraceOption) traceConfig {
+	conf := traceConfig{tp: otel.GetTracerProvider()}
+	for _, o := range options {
+		conf = o.apply(conf)
+	}
+	return conf
+}
+
+type traceConfig struct {
+	tp trace.TracerProvider
+}
+
+// TraceOption applies a configuration option value to an OpenCensus bridge
+// Tracer.
+type TraceOption interface {
+	apply(traceConfig) traceConfig
+}
+
+// traceOptionFunc applies a set of options to a config.
+type traceOptionFunc func(traceConfig) traceConfig
+
+// apply returns a config with option(s) applied.
+func (o traceOptionFunc) apply(conf traceConfig) traceConfig {
+	return o(conf)
+}
+
+// WithTracerProvider specifies a tracer provider to use for creating a tracer.
+func WithTracerProvider(tp trace.TracerProvider) TraceOption {
+	return traceOptionFunc(func(conf traceConfig) traceConfig {
+		conf.tp = tp
+		return conf
+	})
+}
+
+type metricConfig struct{}
+
+// MetricOption applies a configuration option value to an OpenCensus bridge
+// MetricProducer.
+type MetricOption interface {
+	apply(metricConfig) metricConfig
+}

bridge/opencensus/metric.go

@@ -29,15 +29,13 @@ import (
 	"go.opentelemetry.io/otel/sdk/resource"
 )
 
-const scopeName = "go.opentelemetry.io/otel/bridge/opencensus"
-
 type producer struct {
 	manager *metricproducer.Manager
 }
 
 // NewMetricProducer returns a metric.Producer that fetches metrics from
 // OpenCensus.
-func NewMetricProducer() metric.Producer {
+func NewMetricProducer(opts ...MetricOption) metric.Producer {
 	return &producer{
 		manager: metricproducer.GlobalManager(),
 	}

example/opencensus/main.go

@@ -78,8 +78,7 @@ func tracing(otExporter sdktrace.SpanExporter) {
 	otel.SetTracerProvider(tp)
 
 	log.Println("Installing the OpenCensus bridge to make OpenCensus libraries write spans using OpenTelemetry.")
-	tracer := tp.Tracer("simple")
-	octrace.DefaultTracer = opencensus.NewTracer(tracer)
+	opencensus.InstallTraceBridge()
 	tp.ForceFlush(ctx)
 
 	log.Println("Creating OpenCensus span, which should be printed out using the OpenTelemetry stdouttrace exporter.\n-- It should have no parent, since it is the first span.")