mirror of
https://github.com/open-telemetry/opentelemetry-go.git
synced 2025-01-18 03:22:12 +02:00
Opencensus bridge: migrate from README to Go docs (#4561)
This commit is contained in:
David Ashpole
GitHub
parent
d3e31c3d93
commit
acf7146b56
@ -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.
|
||||
@ -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
bridge/opencensus/example_test.go
Normal file
44
bridge/opencensus/example_test.go
Normal file
@ -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))
|
||||
}
|
||||
Loading…
x
Reference in New Issue
Block a user