Configuring end-user monitoring

In contrast to other types of monitoring data, such as infrastructure or application data, end-user monitoring is always collected from untrusted devices that runs within the global internet or a local intranet. For this reason, extra configuration steps need to be taken to ensure that end-users' web browsers and mobile devices can establish a secure connection by using a public domain name that is under control of your organization. In addition, ensure that end-users gain access to only the specific end-user monitoring endpoint, instead of 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) Instana backend exposes HTTP end-user monitoring endpoints under port 86 (HTTP) and 446 (HTTPS). These ports can be made available on the internet or intranet, such as directly or through reverse proxying, to allow download of the JavaScript agent and data acceptance. The number of these ports is deliberately reduced to a minimum to reduce possible attack vectors and to allow simple deployment of the monitoring endpoint.

The ports are deliberately not 80 and 443 because these ports are resevered for access to Instana's user interface. By separating data ingress and user interface, it becomes easier to securely deploy the Instana 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

In the Instana UI, you are recommended to use the URL of the monitoring endpoint as trackingBaseUrl. A valid value for trackingBaseUrl might be https://{{instana_server}}:446/eum/.

Exposing the monitoring endpoint to end-users

You are recommended to expose the monitoring endpoint to end-users by using a reverse proxy, such as NGINX or Apache HTTPd. By doing so, you can ensure that traffic is properly routed from the internet or intranet through your networks to the monitoring endpoint. Furthermore, it enables you to expose the monitoring endpoint under your domain name, with port 443 that uses Transport-Layer Security (TLS), your own certificates, and load balancers (if any)! However, you can decide to allow access to the ports 86 and 446 directly from the internet.

Runnable examples are provided to show how to configure reverse proxies for the monitoring endpoint. These examples also show which headers need to be added or proxied, such as the need for a X-Forwarded-For header.

Do not reconfigure the NGINX, which is installed automatically as part of the self-hosted (on-premises) Instana backend setup. This NGINX is used to allow access to the Instana UI and API, and is therefore subject to different security requirements and update lifecycles. More specifically, the NGINX configuration might be overwritten on subsequent Instana self-hosted (on-premises) Instana backend updates. It can easily lead to an insecure configuration that grants end-users access to the Instana sign-in screen, APIs, and assets.

Make sure to configure the monitoring endpoint within Instana as described in End-user monitoring (EUM) settings so that the Instana UI can provide correct JavaScript agent and mobile app agent installation instructions.

Configuring secure connection between browsers and the reverse proxy

You are recommended to expose the monitoring endpoint with the HTTPS port. You can configure Transport-Layer Security (TLS) for your network under the same domain name with valid signed certificates.

If you don't have a certificate authority but use self-signed certificates, you need set up a reverse proxy or load balancer to proxy requests to both the monitored websites and the monitoring endpoint, and configure the proxy with your self-signed certificates.

For example, you configure the proxy with two locations as https://proxy-server/website and https://proxy-server/eum/. Then, if the end user accepts the incoming self-signed certificate for https://proxy-server, this certificate works for both the websites and the monitoring endpoint.

For information about how to generate your own self-signed certificates, refer to the installation documentation.

GeoLite2 database

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

  1. Download the GeoLite2 database, such as from https://packages.instana.io by running the following command:

    instana geodb download -k <agentKey>

  2. Update the database that is internally used .

    instana geodb update -f <path/to/file>

  3. Apply the changes.

    instana update -f /path/to/settings.hcl

Make sure to comply with the GeoLite2 EULA.

Analyzing issues

To analyze issue, do the following actions:

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

    • If it fails, and you use a proxy, keep in mind that the path to the JavaScript file is probably changed. With the example proxy configurations before, the path is /eum.min.js. If you proxy the eum-acceptor under a subpath, check whether you take the trailing slashes into account, that is, does your proxy strip the /eum path?
    • If it fails, and you don't use a proxy, keep in mind that the Instana monitoring endpoint binds to only ports 86 and 446.
    • If it still doesn't work, contact support and explain the setup, send the proxy configuration, and explain how you try to access the script.

  2. Add the website monitoring snippet to your application.

    • If you don't see any website data, use the website debugging script. Instead of accessing eum.min.js, use eum.debug.js. This logs 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 can 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) are returned by the proxy as a result of this call.
    • If it still doesn't work, contact support and explain the setup, send the proxy configuration, explain how you try to access the script, and send the output of the debug script.