| 1 |
// Copyright The OpenTelemetry Authors |
| 2 |
// SPDX-License-Identifier: Apache-2.0 |
| 3 |
|
| 4 |
// Package opencensus provides a migration bridge from OpenCensus to |
| 5 |
// OpenTelemetry for metrics and traces. The bridge incorporates metrics and |
| 6 |
// traces from OpenCensus into the OpenTelemetry SDK, combining them with |
| 7 |
// metrics and traces from OpenTelemetry instrumentation. |
| 8 |
// |
| 9 |
// # Migration Guide |
| 10 |
// |
| 11 |
// For most applications, it would be difficult to migrate an application |
| 12 |
// from OpenCensus to OpenTelemetry all-at-once. Libraries used by the |
| 13 |
// application may still be using OpenCensus, and the application itself may |
| 14 |
// have many lines of instrumentation. |
| 15 |
// |
| 16 |
// Bridges help in this situation by allowing your application to have "mixed" |
| 17 |
// instrumentation, while incorporating all instrumentation into a single |
| 18 |
// export path. To migrate with bridges, a user would: |
| 19 |
// |
| 20 |
// 1. Configure the OpenTelemetry SDK for metrics and traces, with the OpenTelemetry exporters matching to your current OpenCensus exporters. |
| 21 |
// 2. Install this OpenCensus bridge, which sends OpenCensus telemetry to your new OpenTelemetry exporters. |
| 22 |
// 3. Over time, migrate your instrumentation from OpenCensus to OpenTelemetry. |
| 23 |
// 4. Once all instrumentation is migrated, remove the OpenCensus bridge. |
| 24 |
// |
| 25 |
// With this approach, you can migrate your telemetry, including in dependent |
| 26 |
// libraries over time without disruption. |
| 27 |
// |
| 28 |
// # Warnings |
| 29 |
// |
| 30 |
// Installing a metric or tracing bridge will cause OpenCensus telemetry to be |
| 31 |
// exported by OpenTelemetry exporters. Since OpenCensus telemetry uses globals, |
| 32 |
// installing a bridge will result in telemetry collection from _all_ libraries |
| 33 |
// that use OpenCensus, including some you may not expect, such as the |
| 34 |
// telemetry exporter itself. |
| 35 |
// |
| 36 |
// # Limitations |
| 37 |
// |
| 38 |
// There are known limitations to the trace bridge: |
| 39 |
// |
| 40 |
// - The NewContext method of the OpenCensus Tracer cannot embed an OpenCensus |
| 41 |
// Span in a context unless that Span was created by that Tracer. |
| 42 |
// - Conversion of custom OpenCensus Samplers to OpenTelemetry is not |
| 43 |
// implemented, and an error will be sent to the OpenTelemetry ErrorHandler. |
| 44 |
// |
| 45 |
// There are known limitations to the metric bridge: |
| 46 |
// - GaugeDistribution-typed metrics are dropped |
| 47 |
// - Histogram's SumOfSquaredDeviation field is dropped |
| 48 |
package opencensus // import "go.opentelemetry.io/otel/bridge/opencensus" |