Website automatic instrumentation

Instana website automatic instrumentation quickly and easily enables website monitoring by automatically injecting the JavaScript agent into the website with minimum configuration steps and no code changes of the website.

This feature is only available for Apache HTTP Server starting from HTTPd sensor 1.2.12. The option autoPageDetection is available from HTTPd sensor 1.2.19 and EUM sensor 1.0.5.

You can enable and disable End-User Monitoring (EUM) and HTTPd tracing separately, even though they might share the in-process binary for the monitored technology. But if EUM is enabled, enable tracing as well to achieve end-to-end monitoring.

Enabling website automatic instrumentation
Disabling website automatic instrumentation
Match expressions examples
- Examples for request filtering on multiple virtual hosts
- Examples for infrastructure filtering
  - Example 1: Containerized website deployed on a host
  - Example 2: Containerized website deployed in the Kubernetes environment
Working with Apache module mod_deflate

Enabling website automatic instrumentation

To enable website automatic instrumentation, complete the following steps:

Step 1: Create websites

To create the websites that you want to monitor, complete the following steps:

In the Instana UI, go to Websites & Mobile Apps and click Add Website.
Enter a website name, and then click Add Website.
From the Everything's Ready! window, write down the values for reportingUrl, key, and jsAgentUrl. You need to specify these values in the <instana-agent-dir>/etc/instana/configuration.yaml configuration file of the Instana agent in Step 2.

Step 2: Modify the agent configuration file

You must modify the <instana-agent-dir>/etc/instana/configuration.yaml file of the Instana agent where the Apache HTTP Server is present. The following configuration settings for website automatic instrumentation are available in the configuration.yaml file of the Instana agent:

#EUM
#com.instana.plugin.eum:
#  instrumentation:
#    #contentTypes:                       # List of the 'Content-Type' values for matching requests that need to be instrumented,
#                                         #  default values in the list are 'text/html' and 'application/xhtml+xml'.
#    #  - 'text/html'
#    #  - 'application/xhtml+xml'
#    #aggressive: false                   # Indicates whether to instrument with the EUM JavaScript agent if Instana cannot determine
#                                         # the 'Content-Type' of the request, default is false.
#    #######################################################################################################
#    # Following parameters are used as common EUM monitoring configuration.
#    # They can be overwritten by specifying them in the website configuration.
#    #######################################################################################################
#    jsAgentUrl: 'https://eum.instana.io/eum.min.js' # EUM JavaScript agent download URL.
#    reportingUrl: <reportingUrl>                    # The URL to which to send website monitoring data to.
#    trackSessions: true                             # Indicates whether to enable session tracking, default is true.
#    autoPageDetection: true                         # Indicates whether to enable automatic page detection for single-page-application, default is true.
#    #######################################################################################################
#    # Following parameters are used to configure each monitored website.
#    # Optional parameters are commented out by default. Remove the hashtag (#) when needed.
#    #######################################################################################################
#    websites:
#      - name: <WEBSITE_NAME>             # Name of the website for the website configuration in Instana.
#        key: <WEBSITE_KEY>               # Monitoring key for the website configuration in Instana.
#        #enabled: true                   # Indicates whether to enable website monitoring on this website, default is true.
#        #reportingUrl: <reportingUrl>    # The URL to which to send website monitoring data to. Overwrites upper-level setting.
#        #jsAgentUrl: 'https://eum.instana.io/eum.min.js' # JavaScript agent download URL. Overwrites upper-level setting.
#        #trackSessions: true             # Indicates whether to enable session tracking, default is true. Overwrites upper-level setting.
#        #autoPageDetection: true         # Indicates whether to enable automatic page detection for single-page-application, default is true. Overwrites upper-level setting.
#        #mode: 'regular'                 # Mode for monitoring data transmission, default is 'regular'.
#                                         # Available mode is 'regular'.
#        selector:                        # List of match expressions to filter requests.
#          matchExpressions:              # When all match expressions are evaluated to true, the request is monitored.
#                                         # At least one match expression with the key of the 'url' catalog must be defined.
#            - key: 'url/path'            # Key specified in the <catalog>/<resource> format.
#                                         # Available catalogs in the key include 'url' for request filtering plus
#                                         #  'container' and 'k8s' for Web Server infrastructure filtering.
#                                         # Available keys:
#                                         #  'url/hostname', 'url/path', and 'url/filename'
#                                         #  'container/name' and 'container/imagename'
#                                         #  'k8s/namespace', 'k8s/podname', and 'k8s/containername'
#              operator: 'StartWith'      # Match expression operators: 'Contains', 'ContainsIgnoreCase', 'Equals',
#                                         #  'EqualsIgnoreCase', 'StartWith', and 'StartWithIgnoreCase'.
#              values:                    # List of match expression values.
#                - '/'

Follow the comments of each line to configure automatic instrumentation of the EUM website. See the following example:

com.instana.plugin.eum:
  instrumentation:
    jsAgentUrl: 'https://eum.instana.io/eum.min.js'
    reportingUrl: 'https://eum.example.com'
    trackSessions: true
    websites:
      - name: demo
        key: YOURWEBSITEKEYHERE
        selector:
          matchExpressions:
            - key: 'url/hostname'
              operator: 'Equals'
              values:
                - 'example.com'

In this example, the configuration enables website monitoring for all HTTP requests to the hostname example.com. The beacons that are generated are sent to the demo website with the key YOURWEBSITEKEYHERE on the reporting URL https://eum.example.com.

After you save the modified configuration.yaml file, the HTTPd EUM module is automatically downloaded and installed. You can verify the module by checking the instana_tracing.conf file in the HTTPd configuration directory.

Step 3: Restart the web server

If autoRestart is set to true in the HTTPd tracing, then you don't need to manually restart the Apache HTTP Server.

com.instana.plugin.httpd:
  tracing:
    autoRestart: true

Otherwise, gracefully restart the Apache HTTP Server to load the EUM module.

Step 4: Verify on the website dashboard

Make sure that workloads are present on the website, and then go to the website dashboard in the Instana UI to verify that the monitoring data is received.

Disabling website automatic instrumentation

To disable website automatic instrumentation, comment out or remove all the lines for com.instana.plugin.eum in the configuration.yaml file.

Match expressions examples

Examples for request filtering on multiple virtual hosts

The following examples show how to define the match expressions to ensure that the websites are automatically instrumented when you have multiple VirtualHost in the Apache HTTPd configuration.

For example, see the following VirtualHost definition:

Listen 80
<VirtualHost *:80>
    DocumentRoot "/www/example1"
    ServerName www.example.com

    # Other directives here
</VirtualHost>

<VirtualHost *:80>
    DocumentRoot "/www/example2"
    ServerName www.example.org

    # Other directives here
</VirtualHost>

Example 1: Use url/path as key

To filter the requests to monitor, you can use the url/path key as shown in the following configuration:

com.instana.plugin.eum:
  instrumentation:
    jsAgentUrl: 'https://eum.instana.io/eum.min.js'
    reportingUrl: 'https://eum.example.com'
    trackSessions: true
    websites:
      - name: 'website1'
        key: 'WEBSITEKEY1'
        selector:
          matchExpressions:
            - key: 'url/path'
              operator: 'StartWith'
              values:
                - '/products'
                - '/carts'
      - name: 'website2'
        key: 'WEBSITEKEY2'
        selector:
          matchExpressions:
            - key: 'url/path'
              operator: 'StartWith'
              values:
                - '/offers'
                - '/employees'

With this configuration, the EUM data for client requests with a URL path that starts with /products or /carts is displayed on the dashboard for website1. The EUM data for client requests with a URL path that starts with /offers or /employees is displayed on the dashboard for website2.

Example 2: Use url/filename as key

You can also use the url/filename key to match the DocumentRoot as shown in the following configuration:

com.instana.plugin.eum:
  instrumentation:
    jsAgentUrl: 'https://eum.instana.io/eum.min.js'
    reportingUrl: 'https://eum.example.com'
    trackSessions: true
    websites:
      - name: 'website1'
        key: 'WEBSITEKEY1'
        selector:
          matchExpressions:
            - key: 'url/filename'
              operator: 'StartWith'
              values:
                - '/www/example1'
      - name: 'website2'
        key: 'WEBSITEKEY2'
        selector:
          matchExpressions:
            - key: 'url/filename'
              operator: 'StartWith'
              values:
                - '/www/example2'

With this configuration, the EUM data for client requests to the documents in /www/example1 is displayed on the dashboard for website1, and the EUM data for client requests to the documents in /www/example2 is displayed on the dashboard for website2.

Example 3: Use url/hostname as key

To match the ServerName, you can use the url/hostname key as shown in the following configuration:

com.instana.plugin.eum:
  instrumentation:
    jsAgentUrl: 'https://eum.instana.io/eum.min.js'
    reportingUrl: 'https://eum.example.com'
    trackSessions: true
    websites:
      - name: 'website1'
        key: 'WEBSITEKEY1'
        selector:
          matchExpressions:
            - key: 'url/hostname'
              operator: 'Equals'
              values:
                - 'www.example.com'
      - name: 'website2'
        key: 'WEBSITEKEY2'
        selector:
          matchExpressions:
            - key: 'url/hostname'
              operator: 'Equals'
              values:
                - 'www.example.org'

With this configuration, the EUM data for client requests of the server www.example.com is displayed on the dashboard for website1, and the EUM data for client requests of the server www.example.org is displayed on the dashboard for website2.

The url/hostname in this configuration is not the hostname of your host where the HTTPd server is running but the ServerName of your VirtualHost definition in the HTTPd configuration file.

Example 4: Use multiple keys

To filter the requests to monitor, you can use a combination of url/path, url/filename, and url/hostname keys as shown in the following configuration:

com.instana.plugin.eum:
  instrumentation:
    jsAgentUrl: 'https://eum.instana.io/eum.min.js'
    reportingUrl: 'https://eum.example.com'
    trackSessions: true
    websites:
      - name: 'website1'
        key: 'WEBSITEKEY1'
        selector:
          matchExpressions:
            - key: 'url/hostname'
              operator: 'Equals'
              values:
                - 'www.example.com'
            - key: 'url/path'
              operator: 'StartWith'
              values:
                - '/products'
                - '/carts'
      - name: 'website3'
        key: 'WEBSITEKEY3'
        selector:
          matchExpressions:
            - key: 'url/hostname'
              operator: 'Equals'
              values:
                - 'www.example.com'
            - key: 'url/path'
              operator: 'StartWith'
              values:
                - '/offers'
                - '/employees'
      - name: 'website2'
        key: 'WEBSITEKEY2'
        selector:
          matchExpressions:
            - key: 'url/filename'
              operator: 'StartWith'
              values:
                - '/www/example2'

With this configuration, the EUM data for client requests of the server www.example.com is split into two websites: website1 for requests whose url starts with /products or /carts and website3 for requests whose url starts with /offers or /employees. The EUM data for client requests to the documents in /www/example2 is displayed on the dashboard for website2.

Examples for infrastructure filtering

The following examples show how to define the match expressions to ensure that the websites on specific infrastructure deployment are automatically instrumented.

Unlike request filtering, infrastructure filtering is optional.

Example 1: Containerized website deployed on a host

com.instana.plugin.eum:
  instrumentation:
    jsAgentUrl: 'https://eum.instana.io/eum.min.js'
    reportingUrl: 'https://eum.example.com'
    trackSessions: true
    websites:
      - name: 'containerized website'
        key: 'WEBSITEKEY1'
        selector:
          matchExpressions:
            - key: 'url/hostname'
              operator: 'Equals'
              values:
                - 'www.example.com'
            - key: 'container/name'
              operator: 'Equals'
              values:
                - 'example-app'

With this configuration, when the website-deployment container name matches example-app, the EUM data for client requests of the server www.example.com is displayed on the dashboard for containerized website.

Example 2: Containerized website deployed in the Kubernetes environment

com.instana.plugin.eum:
  instrumentation:
    jsAgentUrl: 'https://eum.instana.io/eum.min.js'
    reportingUrl: 'https://eum.example.com'
    trackSessions: true
    websites:
      - name: 'k8s website'
        key: 'WEBSITEKEY1'
        selector:
          matchExpressions:
            - key: 'url/hostname'
              operator: 'Equals'
              values:
                - 'www.example.com'
            - key: 'k8s/namespace'
              operator: 'Equals'
              values:
                - 'prod-example'
            - key: 'k8s/podname'
              operator: 'Equals'
              values:
                - 'example-pod'
            - key: 'k8s/containername'
              operator: 'Equals'
              values:
                - 'example-app'

With this configuration, when the website is deployed to the container example-app on the pod example-pod of the prod-example namespace in the Kubernetes environment, the EUM data for client requests of the server www.example.com is displayed on the dashboard for k8s website.

Working with Apache module mod_deflate

If gzip compression is enabled in the Apache HTTPd server with mod_deflate module, update the Apache configuration to use the website automatic instrumentation feature.

Complete the first 3 steps as described in the enabling website automatic instrumentation section, and then complete the following steps:

Check whether HTTPd EUM module(dem_module) is loaded by your HTTPd server:
```
httpd -M -f <HTTPd_CONF_FILE>
```

Modify the AddOutputFilterByType setting in your HTTPd configuration file to place INSTANA_DEM_OUT before the DEFLATE filter:

<IfModule mod_deflate.c>
  <IfModule mod_filter.c>
    AddOutputFilterByType INFLATE;INSTANA_DEM_OUT;DEFLATE text/html text/plain text/xml text/css text/javascript
    AddOutputFilterByType DEFLATE application/x-javascript application/javascript application/ecmascript
    AddOutputFilterByType DEFLATE application/rss+xml
    AddOutputFilterByType DEFLATE application/wasm
    AddOutputFilterByType DEFLATE application/xml
  </IfModule>
</IfModule>

Gracefully restart your HTTPd server.