opencensus

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:

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

• func InstallTraceBridge(opts ...TraceOption)
• func OCSpanContextToOTel(sc octrace.SpanContext) trace.SpanContext
• func OTelSpanContextToOC(sc trace.SpanContext) octrace.SpanContext
• func Version() string
• type MetricOption
• type MetricProducer
  • func NewMetricProducer(opts ...MetricOption) *MetricProducer
  • func (p *MetricProducer) Produce(context.Context) ([]metricdata.ScopeMetrics, error)
• type TraceOption
  • func WithTracerProvider(tp trace.TracerProvider) TraceOption

Examples

• NewMetricProducer

Functions

func InstallTraceBridge

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

func OCSpanContextToOTel(sc octrace.SpanContext) trace.SpanContext

OCSpanContextToOTel converts from an OpenCensus SpanContext to an OpenTelemetry SpanContext.

func OTelSpanContextToOC

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.

func Version

func Version() string

Version is the current release version of the opencensus bridge.

Types

type MetricOption

type MetricOption interface {
	// contains filtered or unexported methods
}

MetricOption applies a configuration option value to an OpenCensus bridge MetricProducer.

type MetricProducer

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

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))
}

func (*MetricProducer) Produce

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

type TraceOption interface {
	// contains filtered or unexported methods
}

TraceOption applies a configuration option value to an OpenCensus bridge Tracer.

func WithTracerProvider

func WithTracerProvider(tp trace.TracerProvider) TraceOption

WithTracerProvider specifies a tracer provider to use for creating a tracer.