Migrating from OpenTracing to OpenTelemetry

OpenTelemetry is the next version of OpenTracing and OpenCensus. With General Availability for OpenTelemetry near at hand, now is a good time for existing systems to begin considering their upgrade strategy.

This guide is for existing users of OpenTracing looking to switch to OpenTelemetry. We describe and upgrade path for production systems to progressively migrate from OpenTracing to OpenTelemetry, without any downtime.

Stage 1: Install the OpenTelemetry SDKs

In OpenTracing, the tracer implementation is separate from the OpenTracing API and OpenTracing instrumentation.

Both OpenTracing and OpenTelemetry are factored into the same three components:

  • The tracer implementation.
  • The tracing instrumentation.
  • The tracing API which connects the instrumentation to the implementation.

When upgrading, the tracer implementation is the best place to start. The OpenTelemetry SDK contains the new tracer implementation. This component replaces Jaeger, Brave, older Lightstep clients, and other OpenTracing implementations.

The SDK connects to the new OpenTelemetry API, as well as to the old OpenTracing API, making this a backwards and

Enable OpenTracing support

OpenTracing support is not on by default. Each OpenTelemetry SDK comes with an OpenTracing shim which creates a bridge from the OpenTracing API to the OpenTelemetry API. Enabling this shim will connect the new SDK to your existing instrumentation.

OpenTracing shims:

Propagation format

When upgrading, it is critical to ensure that the new implementations are configured to support the same trace propagation format (B3, Trace-Context, Jaeger, etc) which the current tracers are using.

Export Format

Besides OTLP, OpenTelemetry's native data protocol, supports a variety of export formats for connecting to analysis tools, such as jaeger and zipkin.

Use the OpenTelemetry Collectors to translate between data formats.

Stage 2: Roll out new instrumentation

Once the new SDKs have been deployed, verify that no data output has changed unexpectedly, and that all existing monitoring and analysis tools continue to operate as normal.

Stage 3: Verify data quality

For a quick, visual approach to data verification, Lightstep provides a data linting tool, the Instrumentation Quality Score, as part of the Lightstep community tier.

As part of investing in your new observability setup, ensure that the coverage and quality of your new instrumentation is sufficient. Verify the following:

  • Ingress and egress: ensure that context is propagated for all servers and clients.
  • Standardized data: Ensure that semantic conventions are present, with special attention paid to resource and networking conventions.
  • For more information on data quality, check out our guide to Instrumentation Best Practices.

FAQ

Does anything bad happen if I don't upgrade?

If you have already instrumented with OpenTracing, and are happy with your existing solution, there is no need to upgrade at this time. The OpenTracing API is stable and will remain supported in its current frozen state. Check in with your current tracing provider about their expected support timeline and transition plans.

What are the benefits for installing the OpenTelemetry SDK?

If you would like an improved tracer implementation, but would not like to change your instrumentation, you can switch to the OpenTelemetry SDK while continuing to use your existing OpenTracing instrumentation. This will give you access to OpenTelemetry's framework plugins, and (potentially) improved performance.

What are the benefits for switching to OpenTelemetry Instrumentation?

If you are not happy with your current OpenTracing auto-instrumentation, the new OpenTelemetry auto-instrumentation may provide greater detail and a more consistent experience. In this case, removing any OpenTracing instrumentation libraries or agents you have installed, and replacing them with OpenTelemetry auto-instrumentation may provide a better experience. However, be warned that changing the data your system produces may require changes to your Lightstep project, as the existing queries you have created (operation names, attributes, etc) may no longer be correct.