Backend Correlation

Page Load Backend Correlation

To correlate website page loads and backend traces (note: This is not required for XMLHttpRequest / fetch backend correlation), the JavaScript agent needs to be informed about the backend trace ID. This means that the Instana EUM snippet requires a dynamic variable available to the monitored backend. The sensor in the monitored service (e.g. Java, PHP, etc.) will create this ID automatically. Now, let us look at the desired HTML construct which should be sent to users as part of a server response:

<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','//eum.instana.io/eum.min.js','ineum');

  ineum('apiKey', 'someKey');
  ineum('traceId', 'backendTraceId'); //replace 'backendTraceId with the appropriate expression for retrieval
</script>

The second argument to the ineum call at line 8 (name: traceId), in the above snippet, is available to Instana monitored applications automatically. This ID is created by the tracing sensor. All you need to do is to replace the string backendTraceId with a piece of code that will retrieve the actual value. Retrieval of this backend trace ID depends on the language and runtime environment. The following sections show how the value can be retrieved. It is worth noting that the backend trace ID is only available to code when an agent is running. It is designed so that it still works when no agent is running, but the trace ID is empty in those cases.

Retrieving the backend trace ID in Java

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

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

Note: This header is only available when both the Instana agent is installed and when a trace exists or is created by the HTTP request.

Example line of JavaScript for a JSP page: 

ineum('traceId', '<%= request.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 handling incoming HTTP requests. The agent automatically adds an X-INSTANA-T value to that array when a backend trace is created or already exists. Retrieval of this value is easy as the following code listing shows:

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

// for instance
ineum('traceId', '<?php echo $_SERVER["X-INSTANA-T"] ?>' );

// alternative
printf("ineum('traceId', '%s');", $_SERVER["X-INSTANA-T"]);

Note: This header is only available when the Instana extension is installed and when a trace exists or is created by the HTTP request.

Retrieving the backend trace ID in Node.js

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

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

// express.js example with express.js view engines
res.render('/index.html', {
  traceId: req.get('x-instana-t')
});

Note: This header is only available when the Instana Node.js sensor is installed and when a trace exists or is created by the HTTP request.

Retrieving the backend trace ID in .NET

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

For ASP.NET WebForms

ineum('traceId', '<% =HttpContext.Current.Items["X-INSTANA-T"] %>');

For ASP.NET MVC Applications

ineum('traceId', '@Context.ApplicationInstance.Context.Items["X-INSTANA-T"]');

When executing this on a non-instrumented application, the expressions will only return empty strings.

Helper Method: Go

There is a helper method which you can use in your Go application to insert the JavaScript Agent code into the <head> of the view template:

import (
  "github.com/instana/golang-sensor"
)

...
meta := make(map[string]string, 2)
meta["key1"] = "value1"
meta["key2"] = "value2"

instana.EumSnippet("myApiKey", "myTraceId", meta)

Helper Method: Python

To install the JavaScript Agent into a Python application, you can make the following call in your template, view or layout to add the JavaScript Agent to the <head> of your page:

from instana.helpers import eum_snippet

# Returns the JavaScript Agent as a string
eum_snippet(api_key='abc')

# To add additional metadata, you can pass an additional hash
# of key/value pairs that will automatically be added to the
# JavaScript Agent.
metadata = {'username' => user.name}
eum_snippet(api_key='abc', meta=metadata)

Helper Method: Ruby

To install the JavaScript Agent into a Ruby application, you can make the following call in your template, view or layout to add the JavaScript Agent to the <head> of your page:

# Returns the JavaScript Agent as a string
raw ::Instana::Helpers.eum_snippet('example_api_key_string')

# To add additional metadata, you can pass an additional hash
# of key/value pairs that will automatically be added to the
# JavaScript Agent.
metadata = {:username => @user.name}
raw ::Instana::Helpers.eum_snippet('example_api_key_string', metadata)

Note: Make sure to use the raw helper so the javascript isn’t interpolated with escape strings.