Backend correlation

Instana uses backend correlation to create links between user activity, such as website visits and the work created on the backend or server-side. With backend correlation, you can see the following details:

  • The backend work that is run by website activity.
  • The activities that caused the backend work in the trace view.
  • The auxiliary parameters that are used in the backend work that were not captured by tracing in the trace view.

The links are established through the exposure of backend trace IDs to web browsers. The JavaScript agent obtains the backend trace IDs and includes them in the beacons that is transmitted to Instana's servers.

The backend correlation is supported for three types of beacons and three types of events:

  1. Page loads.
  2. Resource or asset retrievals.
  3. HTTP requests through the XMLHttpRequest and fetch APIs.

Backend correlation occurs automatically. However, sometimes automatic backend correlation is not possible due to the following reasons:

The automatic backend correlation process can be configured to work in most circumstances and browsers, see the following sections for configuring it. Due to backend correlation, which works differently per beacon type, the information in this documentation is structured such that the approach is explained per beacon type.

Important to note

You do not need to follow the steps in this document to use Instana's website monitoring. The steps describe how to improve or enable backend correlation, such as to support backend correlation for older web browsers or to support backend correlation across origins. Most of the backend correlations are automatic. See the following steps to extend the backend correlation coverage. These steps are optional. You can follow them in-order, when you identify a missing backend correlation.

Ensure that the backend is traced

Instana can establish a link between backend and website activity when the backend activity is traced. As a prerequisite of correlation, you need to enable the collection of backend data, also known as tracing. To enable tracing, see Tracing in Instana.

When successful, the traced process responds with Server-Timing HTTP response headers. You can inspect what the process is doing through your web browser's development tools. The following screenshot shows what it 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, check the experience with Instana. It helps you to determine whether you want to continue unlocking complete and reliable backend correlation, especially in older web browsers.

An HTTP response that carries a Server-Timing response header

Understanding the concept of origins

If you want to continue to learn more about the backend correlation process, you must have a good understanding of the concept of origins. The Instana FAQ article explains what you need to know about origins to understand the following steps:

Improve the correlation of HTTP requests (XMLHttpRequest/fetch)

An HTTP request with backend correlation

The correlation of XMLHttpRequest and fetch API usages work reliably for all same-origin calls. Due to the same-origin policy and Cross-origin, the automatic HTTP call backend correlation is not possible.

To unlock backend correlation when multiple origins are involved, the 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, see the following screenshot that describes what is required.

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

Improve the correlation of page loads

A page load with backend correlation

Backend traces and website page loads, that is, the retrieval of the initial HTML files, are automatically backend correlated for web browsers that support 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 enable backend correlation, you need to do the following steps:

  1. Retrieve the trace ID on the backend side.
  2. Render the trace ID into Instana's JavaScript snippet

Retrieve the trace ID on the backend side

The following subsections explain how to retrieve the trace ID for various languages that Instana supports. These methods work only when the backend process is traced and when a trace exists or is created by the HTTP request.

Retrieving 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 exists or is created, the agent automatically adds the X-INSTANA-T attribute. To retrieve this value within the JavaScript part, use the following command:

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

Retrieving the backend trace ID in PHP

In PHP, the backend trace ID is available as a value of the $_SERVER array when you are handling incoming HTTP requests. When a backend trace is created or exists, the agent automatically adds the X-INSTANA-T value to that array. To retrieve this value, use the following command:

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

Retrieving the backend trace ID in Node.js

On installing the Node.js and Node.js collector, the backend trace ID is available as a request header on the incoming HTTP requests. When a backend trace exists or is created, the Node.js collector automatically adds the X-INSTANA-T header. To retrieve this value, use the following command:

// 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')

Retrieving the backend trace ID in .NET

For .NET web-applications, retrieving the backend trace ID follows the same pattern as in 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 or 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"]

Retrieving the trace ID in Ruby

The Ruby language agent holds the current tracing context in ::Instana.tracer.context.

The value can be nil if there is no current trace in progress.

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

Retrieving the trace ID in Python

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

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

from instana.singletons import async_tracer as tracer

tracer.active_span and tracer.active_span.context.trace_id

Retrieving 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

After you retrieve 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. This needs to happen on the server-side and commonly done by using template engines, such as Java JSP and Node.js express view engines. The following example shows how to extend Instana's JavaScript snippet with one call to the API with the Mustache template engine. Other template engines can have a 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 or asset retrievals

A resource or asset retrieval with backend correlation

Backend correlation for resources or assets, such as images, JavaScript, and CSS files, is automatic for:

  • Web browsers that support Server-Timing.
  • Resources or 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 data to JavaScript and to the Instana JavaScript agent.

To unlock backend correlation capabilities for the resources that are retrieved from origins different from the origin of the HTML document, see the following screenshot:

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