Configure End-User Monitoring

Introduction

In contrast to other types of monitoring data, e.g. infrastructure or application data, end-user monitoring is always collected from untrusted devices running within the global internet or a local intranet. For this reason additional configuration steps need to be taken in order to ensure that end-users' web browsers and mobile devices can establish a secure connection via a public domain name that is under control of your organization. At the same it needs to be ensured that end-users only gain access to the specific end-user monitoring endpoint and not to any other parts of the monitoring infrastructure.

The following sections explain the relevant monitoring endpoint, the exposed APIs, security considerations and how to make the monitoring endpoint available to your end-users.

Monitoring Endpoint

The Instana Self-Hosted/On-Premises backend exposes HTTP end-user monitoring endpoints under port 86 (HTTP) and 446 (HTTPS). These ports can be made available on the internet/intranet, e.g. directly or through reverse proxying, in order to allow download of the JavaScript agent and data acceptance. The surface area of these ports is deliberately reduced to a minimum in order to reduce possible attack vectors and to allow simple deployment of the monitoring endpoint.

Please note that the ports are deliberately not 80 and 443 as these are resevered for access to Instana's user interface. By separating data ingress and user interface, it becomes easier to securely deploy our end-user monitoring solution.

HTTP requests are accepted on 86 and 446 (proxied to internal port 2999) for the following paths:

  • Website monitoring data acceptance

    • GET /eum/
    • POST /eum/
  • JavaScript agent download

    • GET /eum/eum.min.js
    • GET /eum/eum.min.js.map
    • GET /eum/eum.js
    • GET /eum/eum.js.map
    • GET /eum/eum.debug.min.js
    • GET /eum/eum.debug.min.js.map
    • GET /eum/eum.debug.js
    • GET /eum/eum.debug.js.map
  • Mobile app monitoring data acceptance

    • POST /eum/mobile

Within Instana's user interface we are referring to the URL of the monitoring endpoint as trackingBaseUrl. A valid value for trackingBaseUrl could therefore be https://{{instana_server}}:446/eum/.

Exposing the Monitoring Endpoint to End-Users

We recommend to expose the monitoring endpoint to end-users by means of a reverse proxy, e.g. NGINX or Apache HTTPd. By doing so you can ensure that traffic is properly routed from the internet/intranet through your networks to the monitoring endpoint. It furthermore enables you to expose the monitoring endpoint under your domain name, with port 443 leveraging Transport-Layer Security (TLS), using your own certificates and load balancers (if any)! You can however decide to allow access to ports 86 and 446 directly from the internet.

We provide runnable examples to show how to configure reverse proxies for the monitoring endpoint. These examples also show which headers should be added/proxied, e.g. the need for a X-Forwarded-For header.

Please do not reconfigure the NGINX which is installed automatically as part of the Instana Self-Hosted/On-Premise setup. This NGINX is used to allow access to the Instana user-interface and API and is therefore subject to different security requirements and update lifecycles. More specifically, the NGINX configuration may be overwritten on subsequent Instana Self-Hosted/On-Premise updates. This can easily lead to an insecure configuration granting end-users access to the Instana sign-in screen, APIs and assets.

Please make sure to configure the monitoring endpoint within Instana so that the Instana user-interface can provide correct JavaScript agent and mobile app agent installation instructions.

GeoLite2 Database

Instana makes use of Maxmind's GeoLite2 databases in order to support IP geolocation for end-user monitoring data. Maxmind requires that you periodically update your GeoLite2 database in order to comply with the California Consumer Privacy Act (CCPA). Without this, geographic information will be missing.

  1. Download the GeoLite2 database, e.g. from https://packages.instana.io via
instana geodb download -k <agentKey>
  1. Update the internal used database.
instana geodb update -f <path/to/file>
  1. Apply the changes.
instana update -f /path/to/settings.hcl

Please make sure to comply with the GeoLite2 EULA.

Analyzing Issues

To analyze issue, do the following:

  1. Open the URL to the JavaScript agent manually in the browser. Do you get JavaScript as a response by the server?

    • If this is failing, and you are using a proxy, keep in mind that the path to the JavaScript file probably changed. With our example proxy configs above, the path would be /eum.min.js. If you are proxying the eum-acceptor under a sub-path: Did you take the trailing slashes into account, i.e. does your proxy strip the /eum path?
    • If this is failing, and you aren't using a proxy, keep in mind that the Instana monitoring endpoint only binds to ports 86 and 446.
    • Still not working? Contact support and explain the setup, send the proxy config, and explain how you are trying to access the script.
  2. Add the website monitoring snippet to your application.

    • If you aren't seeing any website data, use the website debug script. Instead of accessing eum.min.js, use eum.debug.js. This will log a bunch of information about configuration and transmission to the browser console. Inspect the console and resolve any further issues.
    • Open the network explorer in your browser (found in the dev tools). You should be able to see outgoing HTTP GET and HTTP POST calls against the configured reporting URL. Make sure that these calls return a status code 200 or 204. Especially make sure that no HTTP redirects (status code 302) is returned by the proxy as a result of this call.
    • Still not working? Contact support and explain the setup, send the proxy config, and explain how you are trying to access the script, as well as the output of the debug script.