Debian Codegraph @

bridge/opencensus/doc.go

raw
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"