Backend Correlation

Instana uses backend correlation to create links between end-user activity, e.g. website visits, and the work created on the backend/server-side. Backend correlation enables you to:

  • Understand from within the trace view, what activity caused the backend work and, in turn, reveal which auxiliary parameters used in the backend work that were not captured by tracing.
  • Understand the details of what backend work is executed by website activity.

This link is generally established through the exposure of backend trace IDs to web browsers. The JavaScript agent picks up these trace IDs and includes them in the beacons that are transmitted to Instana's servers.

Backend correlation is currently supported for three types of beacons and therefore, three types of events:

  1. Page loads.
  2. Resource/asset retrievals.
  3. HTTP requests (via the XMLHttpRequest and fetch APIs).

Wherever possible, backend correlation occurs entirely automatically; however, there are cases in which automatic backend correlation is not possible. For example…

Fortunately, the automatic backend correlation process can be configured to work in most circumstances and browsers. This document describes how to do so. Due to backend correlation having to work slightly differently per beacon type, this page is structured so that the approach is explained per beacon type.

Important to note

You do not have to follow this guide to use Instana's website monitoring. This guide describes how to improve / enable backend correlation, e.g. to support backend correlation for older web browsers or to support backend correlation across origins. Most of the backend correlation mechanisms work out of the box without any manual work. This guide explains additional steps you can take to extend backend correlation coverage. Please note that these are fully optional. We recommend that you follow them in-order, when you identify a missing (but desired) backend correlation.

Ensure the backend is traced

We can only establish a link between backend and website activity when the backend activity is recorded, i.e. traced. This means installing the Instana agent and, depending on the language being used, enabling tracing.

When successful, the traced process begins to respond with Server-Timing HTTP response headers. You can inspect what the process is doing via your web browser's development tools. The following picture shows what this looks like with Google Chrome's development tools.

Getting to this point means that Instana's automatic mechanisms can start working. If you weren't tracing your processes before, we recommend checking the experience in Instana. This will help you to determine whether you want to continue unlocking complete and reliable (especially in older web browsers) backend correlation.

A HTTP response that carries a Server-Timing response header

Understand what an origin is

If you got to this point and want to go further, we recommend that you have a good understanding of the concept of origins. The Instana FAQ article explains what you need to know about origins in order to continue reading and comprehending the following steps.

Improve the correlation of HTTP requests (XMLHttpRequest/fetch)

An HTTP request with backend correlation

Our customers commonly find this to be the most valuable backend correlation type. The correlation of XMLHttpRequest and fetch API usages work reliably out of the box for all same-origin calls. Due to the same-origin policy, Cross-origin HTTP call backend correlation is not possible automatically out of the box.

To unlock backend correlation when multiple origins are involved, cross-origin resource sharing (CORS) is used. CORS is a mechanism with which small controlled holes are opened within the same-origin policy security mechanism. To address the same-origin policy imposed restrictions, the following picture describes what is required.

Picture explaining cross-origin capable XMLHttpRequest / fetch backend correlations.

Improve the correlation of page loads

A page load with backend correlation

Backend traces and website page loads, i.e. the retrieval of the initial HTML file, are automatically backend correlated for web browsers supporting Server-Timing. By manually exposing the trace ID of the initial page load to the JavaScript agent, it is possible to enable backend correlation for all web browsers. To achieve this, do the following:

  1. Retrieve the trace ID on the backend side (see the following sections).
  2. Render the trace ID into Instana's JavaScript snippet.

Retrieve the trace ID on the backend side

The following sub-sections explain how to retrieve the trace ID for the various languages we support. Please note, these instructions work only when the backend process is traced and when a trace exists or is created by the HTTP request.

Retrieve the trace ID in Java

In Java, the backend trace ID is available as a request attribute on incoming HTTP requests. When a backend trace is created or already exists, the agent automatically adds an X-INSTANA-T attribute. Retrieval of this value within the JavaScript part is shown in the following code:

// via plain Java Servlet request object (standard API)
// http://docs.oracle.com/javaee/6/api/javax/servlet/ServletRequest.html
servletRequest.getAttribute("X-INSTANA-T")

Retrieve the backend trace ID in PHP

In PHP, the backend trace ID is available as a value of the $_SERVER array when handling incoming HTTP requests. When a backend trace is created or already exists, the agent automatically adds an X-INSTANA-T value to that array. Retrieval of this value is shown in the following code:

// via the  $_SERVER superglobal array (standard API)
// http://php.net/manual/en/reserved.variables.server.php
$_SERVER["X-INSTANA-T"]

Retrieve the backend trace ID in Node.js

With Node.js and our Node.js collector installed, the backend trace ID is available as a request header on incoming HTTP requests. When a backend trace is created or already exists, the Node.js collector automatically adds an X-INSTANA-T header. Retrieval of this value is shown in the following code:

// via plain Node.js HTTP request objects (standard API)
// https://nodejs.org/api/http.html#http_class_http_incomingmessage
req.headers['x-instana-t']

// via express.js request objects
// https://expressjs.com/en/4x/api.html#req.get
req.get('x-instana-t')

Retrieve the backend trace ID in .NET

For .NET web-applications, retrieval of the backend trace ID follows the same pattern as per the other languages. Depending on which framework you are using, you need to use different expressions to extract the backend trace ID. The tracer adds the trace ID to the context of the application upon request/response, which you can then extract as follows:

// For ASP.NET WebForms
HttpContext.Current.Items["X-INSTANA-T"]

// For ASP.NET MVC Applications
Context.ApplicationInstance.Context.Items["X-INSTANA-T"]

Retrieve the trace ID in Ruby

The Ruby language agent holds the current tracing context in ::Instana.tracer.context. Note that this can be nil if there is no current trace in progress.

::Instana.tracer.context &&  
  ::Instana::Util.id_to_header(::Instana.tracer.context.trace_id)

Retrieve the trace ID in Python

For Python applications, the location current trace ID depends on whether you are using a synchronous or asynchronous framework.

# Synchronous (Django, Flask etc..)
from instana.singletons import tracer

# Asynchronous (Tornado, AIOHTTP etc..)
from instana.singletons import async_tracer as tracer

tracer.active_span and tracer.active_span.context.trace_id

Retrieve the trace ID in Go

For Go applications, the trace ID is available on the current span:

import instana "github.com/instana/go-sensor"

span := opentracing.StartSpan("MySpanName)
spanContext := span.Context().(instana.SpanContext)
traceId := instana.FormatID(spanContext.TraceID)

Add the trace ID to Instana's JavaScript snippet

Once you understand how to access the trace ID on the server-side, you need to extend Instana's JavaScript snippet with one call to the ineum('traceId', {{TRACE_ID}}); API. Please note, this needs to happen on the server-side and this is commonly done using server-side template engines, e.g. Java JSP, Node.js express view engines. The following example shows how to do this with the Mustache template engine. Other template engines may have a slightly different syntax.

<script>
  (function(i,s,o,g,r,a,m){i['InstanaEumObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://eum.instana.io/eum.min.js','ineum');

  // API calls as generated by the Instana user interface

  ineum('traceId', '{{TRACE_ID}}');
</script>

Improve the correlation of resource/asset retrievals

A resource / asset retrieval with backend correlation

Backend correlation for resources/assets, e.g., images, JavaScript, and CSS files, is automatic for:

  • Web browsers that support Server-Timing.
  • Resources/assets that are served from the same origin as the HTML document.

To unlock backend correlation when multiple origins are involved, use the Timing-Allow-Origin response header. This header instructs the timing allow check to expose the Server-Timing data to JavaScript and therefore to our JavaScript agent.

To unlock backend correlation capabilities for resources that are retrieved from origins different than the origin of the HTML document, the following picture describes what is required.

Picture explaining cross-origin capable resource / asset retrieval backend correlations.