OpenTracing

Instana provides the flexibility on how to capture traces. Regardless of its origin, every trace is treated equally. If you require greater control and flexibility of what exactly gets traced, OpenTracing, a vendor-neutral API for tracing applications, is an option for you.

Instana supports OpenTracing as defined in the OpenTracing specification for the following languages:

Technology Details
Crystal Link
Go Link
Java Link
Node.js Link
PHP Link
Python Link
Ruby Link

In most cases, OpenTracing and other tracing strategies are independent of each other. Although you can use each simultaneously and independently, the strategies themselves cannot be combined to contribute to individual traces. The exceptions, in this case, are Python and GoLang, where OpenTracing doubles as the Instana AutoTrace SDK.

Example - tracing Node.js applications

The following example shows how to use Instana OpenTracing for Node.js applications:

const instana = require('@instana/collector');

// Always initialize the sensor as the first module inside the application.
instana({
  tracing: {
    enabled: true
  }
});

const opentracing = require('opentracing');

// optionally use the opentracing provided singleton tracer wrapper
opentracing.initGlobalTracer(instana.opentracing.createTracer());

// retrieve the tracer instance from the opentracing tracer wrapper
const tracer = opentracing.globalTracer();

// start a new trace with an operation name
const span = tracer.startSpan('auth');

// mark operation as failed
span.setTag(opentracing.Tags.ERROR, true);

// finish the span and schedule it for transmission to instana
span.finish();

OpenTracing best practices

When OpenTracing is used, see the following OpenTracing best practices to fully utilize your Instana dashboard.

For important steps agnostic to a tracing strategy, see our custom tracing best practices docs.

Tags for improved processing

Instana performs advanced processing and analysis on all incoming data to best monitor, learn from and alert on your applications and infrastructure. This includes OpenTracing spans.

To get the most benefit out this analysis and processing, adding the appropriate OpenTracing tags to your spans allows Instana to best analyze and act upon incoming spans.

For example, the following Python OpenTracing code provides very little information:

import opentracing

with opentracing.tracer.start_active_span('vanilla') as pscope:
  # ...
  # do something that takes 50ms
  # ...
  pscope.span.log_kv({"foo": "bar"})

From this code, we know only that it is a span named vanilla that took 50 ms of time. We do not know the type of span it was such as an HTTP, RPC, or Messaging span. We do not know what happened during that time, such as communicating with any other component in your infrastructure.

Instead, if you provide the appropriate contextual OpenTracing tags, Instana can better analyze and extract information from that span to act on.

import opentracing
import opentracing.ext.tags as ext

with opentracing.tracer.start_active_span('webserver') as pscope:
    pscope.span.set_tag(ext.SPAN_KIND, "entry")
    pscope.span.set_tag(ext.PEER_HOSTNAME, "localhost")
    pscope.span.set_tag(ext.HTTP_URL, "/python/simple/two")
    pscope.span.set_tag(ext.HTTP_METHOD, "POST")
    pscope.span.log_kv({"foo": "bar"})

    # ...
    # work that took 50ms
    # ...

    pscope.span.set_tag(ext.HTTP_STATUS_CODE, 204)

This well annotated span tells Instana much more about what happened in the context of this span. From the tags provided we know that this is an incoming webserver request to /python/simple/two and the resulting HTTP status code was 204.

A well annotated span such as above allows Instana to extract services, monitor connections (and their health) and overall provide a richer experience in your dashboard.

See the OpenTracing specification which defines the authoritative list of all supported OpenTracing tags.

peer.service is optional

Set the peer.service tag if you don't know the remote side is instrumented. In general, it is not required as long as the remote side is monitored by Instana and in that case, it will automatically have a service name set. If peer.service is set in the client call and the server is instrumented and has a custom service name, the results are undefined.

Additional information

See the OpenTracing portal for more explanations, quick start guides and more.