README
¶
OpenTelemetry/OpenCensus Bridge
Documentation
¶
Overview ¶
Package opencensus provides a migration bridge from OpenCensus to 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.
Migration Guide ¶
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.
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:
- Configure the OpenTelemetry SDK for metrics and traces, with the OpenTelemetry exporters matching to your current OpenCensus exporters.
- Install this OpenCensus bridge, which sends OpenCensus telemetry to your new OpenTelemetry exporters.
- Over time, migrate your instrumentation from OpenCensus to OpenTelemetry.
- 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 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:
- GaugeDistribution-typed metrics are dropped
- Histogram's SumOfSquaredDeviation field is dropped
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InstallTraceBridge ¶ added in v0.43.0
func InstallTraceBridge(opts ...TraceOption)
InstallTraceBridge installs the OpenCensus trace bridge, which overwrites the global OpenCensus tracer implementation. Once the bridge is installed, spans recorded using OpenCensus are redirected to the OpenTelemetry SDK.
func OCSpanContextToOTel ¶ added in v0.23.0
func OCSpanContextToOTel(sc octrace.SpanContext) trace.SpanContext
OCSpanContextToOTel converts from an OpenCensus SpanContext to an OpenTelemetry SpanContext.
func OTelSpanContextToOC ¶ added in v0.23.0
func OTelSpanContextToOC(sc trace.SpanContext) octrace.SpanContext
OTelSpanContextToOC converts from an OpenTelemetry SpanContext to an OpenCensus SpanContext, and handles any incompatibilities with the global error handler.
Types ¶
type MetricOption ¶ added in v0.43.0
type MetricOption interface {
// contains filtered or unexported methods
}
MetricOption applies a configuration option value to an OpenCensus bridge MetricProducer.
type MetricProducer ¶ added in v0.43.0
type MetricProducer struct {
// contains filtered or unexported fields
}
MetricProducer implements the go.opentelemetry.io/otel/sdk/metric.Producer to provide metrics from OpenCensus to the OpenTelemetry SDK.
func NewMetricProducer ¶ added in v0.35.0
func NewMetricProducer(opts ...MetricOption) *MetricProducer
NewMetricProducer returns a metric.Producer that fetches metrics from OpenCensus.
Example ¶
package main
import (
"go.opentelemetry.io/otel/bridge/opencensus"
"go.opentelemetry.io/otel/sdk/metric"
)
func main() {
// 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))
}
Output:
func (*MetricProducer) Produce ¶ added in v0.43.0
func (p *MetricProducer) Produce(context.Context) ([]metricdata.ScopeMetrics, error)
Produce fetches metrics from the OpenCensus manager, translates them to OpenTelemetry's data model, and returns them.
type TraceOption ¶ added in v0.43.0
type TraceOption interface {
// contains filtered or unexported methods
}
TraceOption applies a configuration option value to an OpenCensus bridge Tracer.
func WithTracerProvider ¶ added in v0.43.0
func WithTracerProvider(tp trace.TracerProvider) TraceOption
WithTracerProvider specifies a tracer provider to use for creating a tracer.
Source Files
Directories