opencensus

package module
v1.28.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 2, 2024 License: Apache-2.0 Imports: 13 Imported by: 32

README

OpenTelemetry/OpenCensus Bridge

PkgGoDev

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

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.

func Version added in v0.43.0

func Version() string

Version is the current release version of the opencensus bridge.

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

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.

Directories

Path Synopsis
examples
bridge Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL