Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.
To try the preview for RUM SDK Auto-Injection, follow the setup instructions below.

Overview

Datadog RUM Server-Side Instrumentation (Auto-Instrumentation) lets you opt into Real User Monitoring (RUM) automatically by instrumenting web applications served through a web server or proxy.

RUM Auto-Instrumentation works by injecting a RUM SDK JavaScript scriptlet into the HTML responses being served through a web server or proxy.

After your applications have been instrumented, you can configure your RUM application in Datadog.

Limitations

The available functionality has the following important limitations:

  • If proxying compressed traffic, the Auto-Instrumentation method is not able to inject the JS scriptlet into the HTML traffic.
  • This instrumentation method does not support any advanced RUM configurations. However, allowedTracingUrls and excludedActivityUrls are supported for NGINX web servers.
  • If NGINX or IIS is acting as a proxy and the upstream server has end-to-end encryption (like TLS) enabled, the module cannot inject RUM. Ensure the web server is set up for TLS origination for successful instrumentation.
  • (Windows IIS only) Configuration for Auto-Instrumentation is only available per Windows IIS site.

Prerequisites

The automatic installation method requires that you have the Datadog Agent installed.

Set up your RUM application

To request support for a web server that is not listed here, fill out this form.

The Auto-Instrumentation method leverages the NGINX Dynamic Modules capability to implement a response body filter. The filter injects the RUM SDK into the response body for responses identified as HTML. For more granular control over how configuration files or permissions are handled, you can also install NGINX manually.

To automatically instrument your RUM application:

  1. In Datadog, navigate to the Digital Experience > Add an Application Page and select the JavaScript (JS) application type.

  2. Select Auto-Instrumentation and NGINX.

  3. Set your Session and Session Replay sample rates. See guidance on configuring sampling.

  4. Copy and run the installer command to load the Datadog NGINX Module with the RUM SDK Injector onto NGINX.

  5. After the installer successfully installs the SDK Injector, restart NGINX to begin collecting RUM sessions.

  6. (Optional) To verify the module is successfully injecting the RUM Browser SDK into HTML pages, check the NGINX error logs for relevant messages. The module logs important steps during the injection process. Ensure that NGINX is configured with at least the INFO log level with the following:

    error_log <file> info;
    

Download the appropriate .tgz file

  1. Use the .tgz file corresponding to your version of NGINX. You can find all the relevant .tgz files listed by NGINX version under Reference.
  2. Extract the tarball to extract the ngx_http_datadog_module.so file. Move it to a location that NGINX has access to (referenced as <RUM_MODULE_PATH> in the steps below).

Update NGINX configuration

  1. The nginx.conf file is usually located in NGINX’s configuration directory. Add the following line to load the module:

    load_module <RUM_MODULE_PATH>;
    
  2. Then in the http/server/location section, add the following:

    # APM Tracing is enabled by default. The following line disables APM Tracing.
    datadog_disable;
    datadog_rum on;
    datadog_rum_config "v5" {
      "applicationId" "<DATADOG_APPLICATION_ID>";
      "clientToken" "<DATADOG_CLIENT_TOKEN>";
      "site" "<DATADOG_SITE>";
      "service" "my-web-application";
      "env" "production";
      "version" "1.0.0";
      "sessionSampleRate" "100";
      "sessionReplaySampleRate" "100";
      "trackResources" "true";
      "trackLongTasks" "true";
      "trackUserInteractions" "true";
    }
    

Restart your server

  1. Restart the NGINX server to begin collecting data for your Datadog RUM application. By default, the RUM SDK is injected to all HTML documents. You may need to clear your browser cache.

  2. (Optional) To verify the module is successfully injecting the RUM Browser SDK into HTML pages, check the NGINX error logs for relevant messages. The module logs important steps during the injection process. Ensure that NGINX is configured with at least the INFO log level with the following:

    error_log <file> info;
    

Auto-Instrumentation leverages a Windows module that injects the RUM SDK into the response body for responses served by the IIS instance.

  1. In Datadog, navigate to the Digital Experience > Add an Application Page and select the JavaScript (JS) application type.
  2. Select Auto-Instrumentation and Windows IIS.
  3. Set up the IIS module using either the GUI installer or command line as described below:
  1. Download the Datadog RUM installer.
  2. Follow the installer as an administrator by opening the .msi file.
  3. Follow the prompts and accept the license agreement.
  4. Set your Session and Session Replay sample rates. See guidance on configuring sampling.
  5. Copy and run the config command shown for each IIS site that you wish to inject RUM into.
  1. Run the Powershell command line as an administrator.
  2. Set your Session and Session Replay sample rates. See guidance on configuring sampling.
  3. Copy and run the config command shown for each IIS site that you wish to inject RUM into.

Updating your RUM application

You can adjust your Session Sampling and Session Replay Sampling rates from the Application Management page.

To update your RUM Application:

  1. Go to your RUM application from the Application Management list.
  2. On the Instrument your application page, adjust the slider or enter a specific percentage in the input box for Session Sampling or Session Replay Sampling.
  3. Copy and run the installer command in your NGINX.conf file.

To update your RUM Application:

  1. Go to your RUM application from the Application Management list.
  2. On the Instrument Your Application page, adjust the slider or enter a specific percentage in the input box for Session Sampling or Session Replay Sampling.
  3. Copy and replace the code in the Datadog RUM config file for the IIS site that you instrumented.

Troubleshooting

NGINX stops responding

Since the module is in Preview, it’s possible NGINX may stop serving requests, particularly after installation. If you experience this issue, contact Datadog support with the following information to help us investigate and resolve the issue:

  • Your NGINX configuration file
  • Any relevant error logs

RUM is not injected

If you notice that RUM is not being injected into HTML pages, consider the following potential causes:

  • Content-Type mismatch: RUM is injected only into HTML pages. If the Content-Type header does not correctly indicate text/html, the injection is skipped.
  • Content compression by upstream server: If NGINX is acting as a proxy and the upstream server has content compression (like gzip, zstd, or Brotli) enabled, the module may not inject RUM. Ensure that content compression is disabled on the upstream server and configure NGINX to compress the content.

Reference

NGINX modules

Further reading