Skip to content

Commit

Permalink
Opencensus bridge: migrate from README to Go docs (#4561)
Browse files Browse the repository at this point in the history
  • Loading branch information
dashpole authored Sep 28, 2023
1 parent d3e31c3 commit acf7146
Show file tree
Hide file tree
Showing 4 changed files with 87 additions and 96 deletions.
81 changes: 0 additions & 81 deletions bridge/opencensus/README.md

This file was deleted.

58 changes: 43 additions & 15 deletions bridge/opencensus/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -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"
44 changes: 44 additions & 0 deletions bridge/opencensus/example_test.go
Original file line number Diff line number Diff line change
@@ -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))
}
File renamed without changes.

0 comments on commit acf7146

Please sign in to comment.