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	For more information, see Monitoring Crystal
Go	For more information, see Monitoring Go
Java	For more information, see Java Trace SDK
Node.js	For more information, see Instana Node.js API
PHP	For more information, see Monitoring PHP
Python	For more information, see Supports Instana Python 2.5.3 and earlier
Ruby	For more information, see Ruby Tracing SDK

Usually, 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 you use OpenTracing, you can see the following OpenTracing best practices to fully use 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 of all incoming data to monitor and learn, and alert your applications and infrastructure, which includes OpenTracing spans.

To obtain the benefit of analysis and processing, you can add the appropriate OpenTracing tags to your spans, which allows Instana to analyze and act upon incoming spans.

For example, the following Python OpenTracing code provides some information:

import opentracing

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

This code indicates that it is a span named vanilla that took 50 ms of time. The type of span, such as an HTTP, RPC, or Messaging span is unknown. The information, such as communicating with any other component in your infrastructure, is missing.

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 annotated span tells Instana more about what happened in the context of this span. From the tags provided, you know that this is an incoming webserver request to /python/simple/two and the resulting HTTP status code was 204.

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

For more information, see the OpenTracing specification, which defines the authoritative list of all supported OpenTracing tags.

peer.service is optional

You must set the peer.service tag if you don't know that the remote side is instrumented. In general, you do not need to set the peer.service tag if Instana monitors the remote side. In this case, a service name is set automatically. If peer.service is set in the client call and the server is instrumented and has a custom service name, the results are undefined.

For more information, see the OpenTracing portal.