The OpenCensus Bridge helps facilitate the migration of an application from OpenCensus to OpenTelemetry.
Caveat about OpenCensus
Installing a metric or tracing bridge will cause OpenCensus telemetry to be exported by OpenTelemetry exporters. Since OpenCensus telemetry uses globals, installing a bridge will result in telemetry collection from all libraries that use OpenCensus, including some you may not expect. For example (#1928), if a client library generates traces with OpenCensus, installing the bridge will cause those traces to be exported by OpenTelemetry.
The Problem: Mixing OpenCensus and OpenTelemetry libraries
In a perfect world, one would simply migrate their entire go application --including custom instrumentation, libraries, and exporters-- from OpenCensus to OpenTelemetry all at once. In the real world, dependency constraints, third-party ownership of libraries, or other reasons may require mixing OpenCensus and OpenTelemetry libraries in a single application.
However, if you create the following spans in a go application:
ctx, ocSpan := opencensus.StartSpan(context.Background(), "OuterSpan") defer ocSpan.End() ctx, otSpan := opentelemetryTracer.Start(ctx, "MiddleSpan") defer otSpan.End() ctx, ocSpan := opencensus.StartSpan(ctx, "InnerSpan") defer ocSpan.End()
OpenCensus reports (to OpenCensus exporters):
OpenTelemetry reports (to OpenTelemetry exporters):
Instead, I would prefer (to a single set of exporters):
[--------OuterSpan------------] [-----MiddleSpan--------] [----InnerSpan------]
The bridge solution
The bridge implements the OpenCensus trace API using OpenTelemetry. This would cause, for example, a span recorded with OpenCensus'
StartSpan() method to be equivalent to recording a span using OpenTelemetry's
tracer.Start() method. Funneling all tracing API calls to OpenTelemetry APIs results in the desired unified span hierarchy.
Starting from an application using entirely OpenCensus APIs:
- Instantiate OpenTelemetry SDK and Exporters
- Override OpenCensus' DefaultTracer with the bridge
- Migrate libraries individually from OpenCensus to OpenTelemetry
- Remove OpenCensus exporters and configuration
To override OpenCensus' DefaultTracer with the bridge:
import ( octrace "go.opencensus.io/trace" "go.opentelemetry.io/otel/bridge/opencensus" "go.opentelemetry.io/otel" ) tracer := otel.GetTracerProvider().Tracer("bridge") octrace.DefaultTracer = opencensus.NewTracer(tracer)
Be sure to set the
Tracer name to your instrumentation package name instead of
OpenCensus and OpenTelemetry APIs are not entirely compatible. If the bridge finds any incompatibilities, it will log them. Incompatibilities include:
- Custom OpenCensus Samplers specified during StartSpan are ignored.
- Links cannot be added to OpenCensus spans.
- OpenTelemetry Debug or Deferred trace flags are dropped after an OpenCensus span is created.
Package opencensus provides a migration bridge from OpenCensus to OpenTelemetry. The NewTracer function should be used to create an OpenCensus Tracer from an OpenTelemetry Tracer. This Tracer can be use in place of any existing OpenCensus Tracer and will generate OpenTelemetry spans for traces. These spans will be exported by the OpenTelemetry TracerProvider the original OpenTelemetry Tracer came from.
There are known limitations to this bridge:
- The AddLink method for OpenCensus Spans is not compatible with the OpenTelemetry Span. No link can be added to an OpenTelemetry Span once it is started. Any calls to this method for the OpenCensus Span will result in an error being sent to the OpenTelemetry default ErrorHandler.
- The NewContext method of the OpenCensus Tracer cannot embed an OpenCensus Span in a context unless that Span was created by that Tracer.
- Conversion of custom OpenCensus Samplers to OpenTelemetry is not implemented. An error will be sent to the OpenTelemetry default ErrorHandler if this is attempted.
- func NewMetricExporter(base metric.Exporter, res *resource.Resource) metricexport.Exporter
- func NewMetricProducer() metric.Producer
- func NewTracer(tracer trace.Tracer) octrace.Tracer
- func OCSpanContextToOTel(sc octrace.SpanContext) trace.SpanContext
- func OTelSpanContextToOC(sc trace.SpanContext) octrace.SpanContext
This section is empty.
This section is empty.
func NewMetricExporter ¶ added in v0.19.0
NewMetricExporter returns an OpenCensus exporter that exports to an OpenTelemetry (push) exporter. Deprecated: Use NewMetricProducer instead.
func NewMetricProducer ¶ added in v0.35.0
NewMetricProducer returns a metric.Producer that fetches metrics from OpenCensus.
func NewTracer ¶
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.
func OCSpanContextToOTel ¶ added in v0.23.0
func OCSpanContextToOTel(sc octrace.SpanContext) trace.SpanContext
OCSpanContextToOTel converts from an OpenCensus SpanContext to an OpenTelemetry SpanContext.
func OTelSpanContextToOC ¶ added in v0.23.0
func OTelSpanContextToOC(sc trace.SpanContext) octrace.SpanContext
OTelSpanContextToOC converts from an OpenTelemetry SpanContext to an OpenCensus SpanContext, and handles any incompatibilities with the global error handler.
This section is empty.