From acf7146b566054dac9e10576a285bd11ed87b7e2 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 28 Sep 2023 04:31:00 -0400 Subject: [PATCH] Opencensus bridge: migrate from README to Go docs (#4561) --- bridge/opencensus/README.md | 81 ----------------------- bridge/opencensus/doc.go | 58 +++++++++++----- bridge/opencensus/example_test.go | 44 ++++++++++++ bridge/opencensus/{bridge.go => trace.go} | 0 4 files changed, 87 insertions(+), 96 deletions(-) delete mode 100644 bridge/opencensus/README.md create mode 100644 bridge/opencensus/example_test.go rename bridge/opencensus/{bridge.go => trace.go} (100%) diff --git a/bridge/opencensus/README.md b/bridge/opencensus/README.md deleted file mode 100644 index 3df9dc7eb07..00000000000 --- a/bridge/opencensus/README.md +++ /dev/null @@ -1,81 +0,0 @@ -# OpenCensus Bridge - -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](https://github.com/open-telemetry/opentelemetry-go/issues/1928)), if a client library generates traces with OpenCensus, installing the bridge will cause those traces to be exported by OpenTelemetry. - -## Tracing - -### 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: - -```go -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): - -``` -[--------OuterSpan------------] - [----InnerSpan------] -``` - -OpenTelemetry reports (to OpenTelemetry exporters): - -``` - [-----MiddleSpan--------] -``` - -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. - -### User Journey - -Starting from an application using entirely OpenCensus APIs: - -1. Instantiate OpenTelemetry SDK and Exporters -2. Override OpenCensus' DefaultTracer with the bridge -3. Migrate libraries individually from OpenCensus to OpenTelemetry -4. Remove OpenCensus exporters and configuration - -To override OpenCensus' DefaultTracer with the bridge: - -```go -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 `"bridge"`. - -#### Incompatibilities - -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. diff --git a/bridge/opencensus/doc.go b/bridge/opencensus/doc.go index 80d80da6f78..ed2a4cfd935 100644 --- a/bridge/opencensus/doc.go +++ b/bridge/opencensus/doc.go @@ -13,23 +13,51 @@ // limitations under the License. // 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. +// OpenTelemetry for metrics and traces. The bridge incorporates metrics and +// traces from OpenCensus into the OpenTelemetry SDK, combining them with +// metrics and traces from OpenTelemetry instrumentation. // -// There are known limitations to this bridge: +// # Migration Guide // -// - 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. +// For most applications, it would be difficult to migrate an application +// from OpenCensus to OpenTelemetry all-at-once. Libraries used by the +// application may still be using OpenCensus, and the application itself may +// have many lines of instrumentation. // -// - The NewContext method of the OpenCensus Tracer cannot embed an OpenCensus -// Span in a context unless that Span was created by that Tracer. +// Bridges help in this situation by allowing your application to have "mixed" +// instrumentation, while incorporating all instrumentation into a single +// export path. To migrate with bridges, a user would: // -// - Conversion of custom OpenCensus Samplers to OpenTelemetry is not -// implemented. An error will be sent to the OpenTelemetry default -// ErrorHandler if this is attempted. +// 1. Configure the OpenTelemetry SDK for metrics and traces, with the OpenTelemetry exporters matching to your current OpenCensus exporters. +// 2. Install this OpenCensus bridge, which sends OpenCensus telemetry to your new OpenTelemetry exporters. +// 3. Over time, migrate your instrumentation from OpenCensus to OpenTelemetry. +// 4. Once all instrumentation is migrated, remove the OpenCensus bridge. +// +// With this approach, you can migrate your telemetry, including in dependent +// libraries over time without disruption. +// +// # Warnings +// +// 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, such as the +// telemetry exporter itself. +// +// # Limitations +// +// There are known limitations to the trace bridge: +// +// - The AddLink method for OpenCensus Spans is ignored, and an error is sent +// to the OpenTelemetry 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, and An error will be sent to the OpenTelemetry ErrorHandler. +// +// There are known limitations to the metric bridge: +// - Summary-typed metrics are dropped +// - GaugeDistribution-typed metrics are dropped +// - Histogram's SumOfSquaredDeviation field is dropped +// - Exemplars on Histograms are dropped package opencensus // import "go.opentelemetry.io/otel/bridge/opencensus" diff --git a/bridge/opencensus/example_test.go b/bridge/opencensus/example_test.go new file mode 100644 index 00000000000..57fef19e168 --- /dev/null +++ b/bridge/opencensus/example_test.go @@ -0,0 +1,44 @@ +// 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_test + +import ( + octrace "go.opencensus.io/trace" + + "go.opentelemetry.io/otel" + "go.opentelemetry.io/otel/bridge/opencensus" + "go.opentelemetry.io/otel/sdk/metric" +) + +func ExampleNewTracer() { + // Create an OpenTelemetry Tracer to use to record spans. + tracer := otel.GetTracerProvider().Tracer("go.opentelemetry.io/otel/bridge/opencensus") + // Overwrite the OpenCensus DefaultTracer so that it uses OpenTelemetry + // rather than OpenCensus. + octrace.DefaultTracer = opencensus.NewTracer(tracer) +} + +func ExampleNewMetricProducer() { + // Create the OpenCensus Metric bridge. + bridge := opencensus.NewMetricProducer() + // Add the bridge as a producer to your reader. + // If using a push exporter, such as OTLP exporter, + // use metric.NewPeriodicReader with metric.WithProducer option. + // If using a pull exporter which acts as a reader, such as prometheus exporter, + // use a dedicated option like prometheus.WithProducer. + reader := metric.NewManualReader(metric.WithProducer(bridge)) + // Add the reader to your MeterProvider. + _ = metric.NewMeterProvider(metric.WithReader(reader)) +} diff --git a/bridge/opencensus/bridge.go b/bridge/opencensus/trace.go similarity index 100% rename from bridge/opencensus/bridge.go rename to bridge/opencensus/trace.go